@friggframework/schemas 2.0.0--canary.700.80ec1cc.0 → 2.0.0--canary.702.047d3c4.0

package/README.md

@@ -41,6 +41,32 @@ if (result.valid) {
 }
 ```
 
+### Integration classes and defaults (ADR-051)
+
+Apps list integration classes, which JSON Schema cannot describe.
+`validateAppDefinition` validates a view of the definition in which each
+class in `integrations`, `adminScripts` and `reports` is replaced by
+`{ Definition }`; `frigg validate` checks the classes themselves.
+
+```javascript
+const { applyAppDefinitionDefaults } = require('@friggframework/schemas');
+// or, without loading Ajv:
+// require('@friggframework/schemas/app-definition').applyAppDefinitionDefaults
+
+const definition = applyAppDefinitionDefaults(require('./index').Definition);
+definition.user.individualUserRequired; // true (schema default)
+```
+
+`applyAppDefinitionDefaults` returns a copy with every `default` declared in
+the app-definition schema applied (only inside blocks the app sets, plus
+blocks that have a default themselves, such as `user`). core's
+`loadAppDefinition` and devtools' `createFriggInfrastructure` call it, so a
+schema default is the runtime default. A schema default must equal what the
+code does when the key is absent; the contract test in
+`packages/devtools/infrastructure/app-definition-schema-contract.test.js`
+checks this for the infrastructure builders. Keys nothing reads are marked
+`"deprecated": true`.
+
 ### Advanced Validation
 
 ```javascript

package/api-module-definition.js

@@ -0,0 +1,93 @@
+/**
+ * API module definition helpers shared by validators and the frigg CLI.
+ * Real Definitions carry classes and functions that JSON Schema cannot
+ * describe; validators check the serialisable view produced here.
+ */
+
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object') return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Schema descriptor for a JavaScript function (see api-module-definition
+ * schema: `{ type: "function", async?: boolean }`).
+ *
+ * @param {Function} fn
+ * @returns {{ type: 'function', async?: boolean }}
+ */
+function toFunctionDescriptor(fn) {
+    const descriptor = { type: 'function' };
+    if (fn && fn.constructor && fn.constructor.name === 'AsyncFunction') {
+        descriptor.async = true;
+    }
+    return descriptor;
+}
+
+/**
+ * JSON Schema cannot describe a JavaScript class or function. Validators
+ * therefore check this serialisable view: the API class becomes an empty
+ * object, functions become `{ type: "function" }` descriptors, and
+ * `undefined` env values are dropped (unset `process.env.*` entries).
+ *
+ * @param {object} definition the `Definition` exported by an API module
+ * @returns {object} a view suitable for the api-module-definition schema
+ */
+function toApiModuleDefinitionSchemaView(definition) {
+    if (!isPlainObject(definition)) return definition;
+
+    const view = { ...definition };
+
+    if (typeof view.API === 'function') {
+        view.API = {};
+    }
+
+    if (typeof view.getName === 'function') {
+        view.getName = toFunctionDescriptor(view.getName);
+    }
+
+    if (isPlainObject(view.requiredAuthMethods)) {
+        const methods = { ...view.requiredAuthMethods };
+        for (const [key, value] of Object.entries(methods)) {
+            if (typeof value === 'function') {
+                methods[key] = toFunctionDescriptor(value);
+            }
+        }
+        view.requiredAuthMethods = methods;
+    }
+
+    if (isPlainObject(view.env)) {
+        const env = {};
+        for (const [key, value] of Object.entries(view.env)) {
+            if (value !== undefined) env[key] = value;
+        }
+        view.env = env;
+    }
+
+    if (isPlainObject(view.manager)) {
+        const manager = { ...view.manager };
+        for (const key of ['Entity', 'Credential']) {
+            if (typeof manager[key] === 'function') {
+                manager[key] = {};
+            }
+        }
+        if (isPlainObject(manager.methods)) {
+            const methods = { ...manager.methods };
+            for (const [key, value] of Object.entries(methods)) {
+                if (typeof value === 'function') {
+                    methods[key] = {};
+                }
+            }
+            manager.methods = methods;
+        }
+        view.manager = manager;
+    }
+
+    return view;
+}
+
+module.exports = {
+    toApiModuleDefinitionSchemaView,
+    toFunctionDescriptor,
+};

package/app-definition.js

@@ -0,0 +1,113 @@
+/**
+ * App definition helpers shared by the runtime (core) and the tooling
+ * (devtools, frigg CLI). See ADR-051.
+ *
+ * This file loads only the JSON schema, not Ajv, so the runtime can apply
+ * the schema defaults at cold start without compiling a validator.
+ */
+
+const appDefinitionSchema = require('./schemas/app-definition.schema.json');
+
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object') return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+
+function cloneDefault(value) {
+    // Schema defaults are JSON values: a JSON round trip copies them fully.
+    return value === undefined ? value : JSON.parse(JSON.stringify(value));
+}
+
+/**
+ * Copy plain objects and arrays, keep everything else (classes, functions,
+ * instances) by reference.
+ */
+function clonePlain(value) {
+    if (Array.isArray(value)) return value.map(clonePlain);
+    if (isPlainObject(value)) {
+        const copy = {};
+        for (const [key, inner] of Object.entries(value)) {
+            copy[key] = clonePlain(inner);
+        }
+        return copy;
+    }
+    return value;
+}
+
+function applyDefaultsInPlace(schema, data) {
+    if (!schema || !isPlainObject(data)) return;
+    const properties = schema.properties || {};
+    for (const [key, propertySchema] of Object.entries(properties)) {
+        if (data[key] === undefined && propertySchema.default !== undefined) {
+            data[key] = cloneDefault(propertySchema.default);
+        }
+        if (isPlainObject(data[key]) && propertySchema.properties) {
+            applyDefaultsInPlace(propertySchema, data[key]);
+        }
+    }
+}
+
+/**
+ * Return a copy of the app definition with every `default` that the
+ * app-definition schema declares applied, the way Ajv `useDefaults` does:
+ * only for properties of objects that exist (a block the app leaves out is
+ * not created unless the block itself has a default, as `user` does). It
+ * also copies the deprecated `user.password` into `user.usePassword` when
+ * only the old spelling is set. Classes and other non-plain values are kept by reference.
+ * The input is not mutated, and the function is idempotent.
+ *
+ * This is the only place schema defaults are applied. core's
+ * loadAppDefinition and devtools' createFriggInfrastructure both call it,
+ * so a default in the schema is a default at runtime.
+ *
+ * @param {object} definition the `Definition` exported by the backend
+ * @returns {object} the definition with defaults applied
+ */
+function applyAppDefinitionDefaults(definition) {
+    if (!isPlainObject(definition)) return definition;
+    const copy = clonePlain(definition);
+    // user.password is the deprecated spelling of user.usePassword.
+    if (
+        isPlainObject(copy.user) &&
+        copy.user.usePassword === undefined &&
+        typeof copy.user.password === 'boolean'
+    ) {
+        copy.user.usePassword = copy.user.password;
+    }
+    applyDefaultsInPlace(appDefinitionSchema, copy);
+    return copy;
+}
+
+// Keys whose entries are classes with a static Definition.
+const CLASS_LIST_KEYS = ['integrations', 'adminScripts', 'reports'];
+
+/**
+ * JSON Schema cannot describe a JavaScript class, and apps list integration
+ * (and admin script, and report) classes. Validators therefore check this serialisable view, in which each
+ * class is replaced by `{ Definition }` (its static Definition). The schema
+ * describes that view; `frigg validate` checks the Definition itself.
+ *
+ * @param {object} definition the `Definition` exported by the backend
+ * @returns {object} a shallow copy with the class lists mapped to views
+ */
+function toAppDefinitionSchemaView(definition) {
+    if (!isPlainObject(definition)) return definition;
+    const view = { ...definition };
+    for (const key of CLASS_LIST_KEYS) {
+        if (Array.isArray(definition[key])) {
+            view[key] = definition[key].map((entry) =>
+                typeof entry === 'function'
+                    ? { Definition: entry.Definition }
+                    : entry
+            );
+        }
+    }
+    return view;
+}
+
+module.exports = {
+    applyAppDefinitionDefaults,
+    toAppDefinitionSchemaView,
+    appDefinitionSchema,
+};

package/index.js

@@ -12,6 +12,13 @@ const path = require('path');
 
 // Import middleware
 const schemaValidationMiddleware = require('./middleware/schema-validation');
+const {
+    applyAppDefinitionDefaults,
+    toAppDefinitionSchemaView,
+} = require('./app-definition');
+const {
+    toApiModuleDefinitionSchemaView,
+} = require('./api-module-definition');
 
 // Initialize AJV with formats
 const ajv = new Ajv({ 
@@ -76,7 +83,13 @@ function validate(schemaName, data) {
  * @returns {object} - Validation result
  */
 function validateAppDefinition(appDefinition) {
-    return validate('app-definition', appDefinition);
+    // Apps list integration classes, which JSON Schema cannot describe:
+    // validate the serialisable view and return the original definition.
+    const result = validate(
+        'app-definition',
+        toAppDefinitionSchemaView(appDefinition)
+    );
+    return { ...result, data: appDefinition };
 }
 
 /**
@@ -89,12 +102,18 @@ function validateIntegrationDefinition(integrationDefinition) {
 }
 
 /**
- * Validate API Module Definition
- * @param {object} apiModuleDefinition - API module definition object to validate  
+ * Validate API Module Definition.
+ * Real Definitions carry classes and functions; validate the serialisable
+ * view and return the original definition (same pattern as validateAppDefinition).
+ * @param {object} apiModuleDefinition - API module definition object to validate
  * @returns {object} - Validation result
  */
 function validateApiModuleDefinition(apiModuleDefinition) {
-    return validate('api-module-definition', apiModuleDefinition);
+    const result = validate(
+        'api-module-definition',
+        toApiModuleDefinitionSchemaView(apiModuleDefinition)
+    );
+    return { ...result, data: apiModuleDefinition };
 }
 
 /**
@@ -357,6 +376,9 @@ module.exports = {
     // Validation functions
     validate,
     validateAppDefinition,
+    applyAppDefinitionDefaults,
+    toAppDefinitionSchemaView,
+    toApiModuleDefinitionSchemaView,
     validateIntegrationDefinition,
     validateApiModuleDefinition,
     validateServerlessConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@friggframework/schemas",
-  "version": "2.0.0--canary.700.80ec1cc.0",
+  "version": "2.0.0--canary.702.047d3c4.0",
   "description": "Canonical JSON Schema definitions for Frigg Framework",
   "main": "index.js",
   "author": "",
@@ -39,7 +39,9 @@
     "validators/",
     "mocks/",
     "middleware/",
+    "app-definition.js",
+    "api-module-definition.js",
     "index.js"
   ],
-  "gitHead": "80ec1cc658ebdfbe53482d0705c42129685eb47f"
+  "gitHead": "047d3c404aa8c9636d6c2c442d28ce5e5fcf6b39"
 }

package/schemas/api-module-definition.schema.json

@@ -27,6 +27,13 @@
       "minLength": 1,
       "maxLength": 100
     },
+    "modelName": {
+      "type": "string",
+      "description": "Entity/credential model name used by the Module runtime (e.g. 'Fathom'). Distinct from moduleName, which is the package identifier.",
+      "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$",
+      "minLength": 1,
+      "maxLength": 100
+    },
     "requiredAuthMethods": {
       "type": "object",
       "description": "Required authentication methods and configuration",
@@ -90,6 +97,22 @@
             "type": {"type": "string", "enum": ["function"]},
             "async": {"type": "boolean", "default": true}
           }
+        },
+        "getAuthorizationRequirements": {
+          "type": "object",
+          "description": "Method that returns the authorization requirements (type, jsonSchema/uiSchema) for non-OAuth flows such as API key",
+          "properties": {
+            "type": {"type": "string", "enum": ["function"]},
+            "async": {"type": "boolean", "default": true}
+          }
+        },
+        "setAuthParams": {
+          "type": "object",
+          "description": "Method that applies authorization parameters (e.g. API key) to the API instance",
+          "properties": {
+            "type": {"type": "string", "enum": ["function"]},
+            "async": {"type": "boolean", "default": true}
+          }
         }
       },
       "additionalProperties": false