feat: Add support for Action Modules

docs/resource-specific-documentation.md

@@ -970,3 +970,162 @@ File: `./risk-assessment/settings.json`
 ```
 
 For more details, see the [Management API documentation](https://auth0.com/docs/api/management/v2#!/Risk_Assessments/get_settings).
+
+## Action Modules
+
+Action modules are reusable code modules that can be shared across multiple Auth0 actions. They allow you to create common utility functions, helpers, and libraries that can be imported and used by any action in your tenant.
+
+### YAML Example
+
+```yaml
+# Contents of ./tenant.yaml
+actionModules:
+  - name: auth-helper
+    code: ./action-modules/auth-helper/code.js
+    dependencies:
+      - name: axios
+        version: 1.6.0
+      - name: jsonwebtoken
+        version: 9.0.0
+    secrets:
+      - name: JWT_SECRET
+        value: ##JWT_SECRET##
+
+  - name: notification-helper
+    code: ./action-modules/notification-helper/code.js
+    dependencies:
+      - name: uuid
+        version: 9.0.0
+    secrets: []
+```
+
+Folder structure when in YAML mode:
+
+```
+./action-modules/
+    /auth-helper/
+        /code.js
+    /notification-helper/
+        /code.js
+./tenant.yaml
+```
+
+### Directory Example
+
+Folder structure when in directory mode:
+
+```
+./action-modules/
+    ./auth-helper.json
+    ./auth-helper/
+        ./code.js
+    ./notification-helper.json
+    ./notification-helper/
+        ./code.js
+```
+
+Contents of `auth-helper.json`:
+
+```json
+{
+  "name": "auth-helper",
+  "code": "./action-modules/auth-helper/code.js",
+  "dependencies": [
+    {
+      "name": "axios",
+      "version": "1.6.0"
+    },
+    {
+      "name": "jsonwebtoken",
+      "version": "9.0.0"
+    }
+  ],
+  "secrets": [
+    {
+      "name": "JWT_SECRET",
+      "value": "##JWT_SECRET##"
+    }
+  ]
+}
+```
+
+Contents of `auth-helper/code.js`:
+
+```javascript
+const jwt = require('jsonwebtoken');
+const axios = require('axios');
+
+/**
+ * Auth Helper Module
+ * Provides JWT validation and token refresh utilities
+ */
+module.exports = {
+  async validateToken(token) {
+    const secret = actions.secrets.JWT_SECRET;
+    try {
+      return jwt.verify(token, secret);
+    } catch (error) {
+      throw new Error('Invalid token: ' + error.message);
+    }
+  },
+
+  async fetchUserData(userId) {
+    const response = await axios.get(`https://api.example.com/users/${userId}`);
+    return response.data;
+  },
+};
+```
+
+### Using Action Modules in Actions
+
+Actions can reference action modules in their configuration:
+
+**YAML Example:**
+
+```yaml
+actions:
+  - name: send-phone-message
+    code: ./actions/send-phone-message/code.js
+    supported_triggers:
+      - id: send-phone-message
+        version: v1
+    modules:
+      - module_name: notification-helper
+        module_version_number: 1
+```
+
+**Directory Example:**
+
+Contents of `actions/send-phone-message.json`:
+
+```json
+{
+  "name": "send-phone-message",
+  "code": "./actions/send-phone-message/code.js",
+  "supported_triggers": [
+    {
+      "id": "send-phone-message",
+      "version": "v1"
+    }
+  ],
+  "modules": [
+    {
+      "module_name": "notification-helper",
+      "module_version_number": 1
+    }
+  ]
+}
+```
+
+The action can then import and use the module in its code:
+
+```javascript
+const notificationHelper = require('actions:notification-helper');
+
+exports.onExecuteSendPhoneMessage = async (event) => {
+  const message = notificationHelper.formatMessage(
+    event.user.phone_number,
+    'Your verification code'
+  );
+};
+```

examples/directory/README.md

@@ -61,6 +61,13 @@ repository =>
       code.js
       current_version.js
     action1.json
+  action-modules
+    auth-helper
+      code.js
+    auth-helper.json
+    notification-helper
+      code.js
+    notification-helper.json
   triggers
     triggers.json
 ```

examples/directory/action-modules/auth-helper.json

@@ -0,0 +1,20 @@
+{
+  "name": "auth-helper",
+  "code": "./action-modules/auth-helper/code.js",
+  "dependencies": [
+    {
+      "name": "axios",
+      "version": "1.6.0"
+    },
+    {
+      "name": "jsonwebtoken",
+      "version": "9.0.0"
+    }
+  ],
+  "secrets": [
+    {
+      "name": "JWT_SECRET",
+      "value": "##JWT_SECRET##"
+    }
+  ]
+}

examples/directory/action-modules/auth-helper/code.js

@@ -0,0 +1,32 @@
+const jwt = require('jsonwebtoken');
+const axios = require('axios');
+
+/**
+ * Auth Helper Module
+ * Provides JWT validation and token refresh utilities
+ */
+module.exports = {
+  /**
+   * Validates a JWT token
+   * @param {string} token - JWT token to validate
+   * @returns {Promise<object>} Decoded token payload
+   */
+  async validateToken(token) {
+    const secret = actions.secrets.JWT_SECRET;
+    try {
+      return jwt.verify(token, secret);
+    } catch (error) {
+      throw new Error('Invalid token: ' + error.message);
+    }
+  },
+
+  /**
+   * Fetches user data from an external API
+   * @param {string} userId - User ID to fetch
+   * @returns {Promise<object>} User data
+   */
+  async fetchUserData(userId) {
+    const response = await axios.get(`https://api.example.com/users/${userId}`);
+    return response.data;
+  }
+};

examples/directory/action-modules/notification-helper.json

@@ -0,0 +1,11 @@
+{
+  "name": "notification-helper",
+  "code": "./action-modules/notification-helper/code.js",
+  "dependencies": [
+    {
+      "name": "uuid",
+      "version": "9.0.0"
+    }
+  ],
+  "secrets": []
+}

examples/directory/action-modules/notification-helper/code.js

@@ -0,0 +1,23 @@
+const { v4: uuidv4 } = require('uuid');
+
+/**
+ * Notification Helper Module
+ * Provides utility functions for notification handling
+ */
+module.exports = {
+  /**
+   * Formats a phone message with tracking metadata
+   * @param {string} recipient - Phone number
+   * @param {string} message - Message content
+   * @returns {object} Formatted message object
+   */
+  formatMessage: function(recipient, message) {
+    return {
+      id: uuidv4(),
+      recipient,
+      message,
+      timestamp: new Date().toISOString(),
+      status: 'pending'
+    };
+  }
+};

examples/directory/actions/action-example.json

@@ -21,4 +21,4 @@
     }
   ],
   "deployed": true
-}
+}

examples/directory/actions/send-phone-message.json

@@ -0,0 +1,29 @@
+{
+  "name": "send-phone-message",
+  "code": "./actions/send-phone-message/code.js",
+  "status": "built",
+  "dependencies": [
+    {
+      "name": "axios",
+      "version": "1.6.0"
+    },
+    {
+      "name": "uuid",
+      "version": "9.0.0"
+    }
+  ],
+  "secrets": [],
+  "supported_triggers": [
+    {
+      "id": "send-phone-message",
+      "version": "v1"
+    }
+  ],
+  "deployed": true,
+  "modules": [
+    {
+      "module_name": "notification-helper",
+      "module_version_number": 1
+    }
+  ]
+}

examples/directory/actions/send-phone-message/code.js

@@ -0,0 +1,36 @@
+const axios = require('axios');
+const { v4: uuidv4 } = require('uuid');
+const { formatMessage } = require('actions:notification-helper');
+
+/**
+ * @type {SendPhoneMessageAction}
+ *
+ * This action demonstrates using an action module to share code
+ * across multiple actions. The notification-helper module provides
+ * utilities for message formatting and tracking.
+ */
+exports.onExecuteSendPhoneMessage = async (event, api) => {
+  const messageId = uuidv4();
+  console.log(`Processing phone message. MessageId: ${messageId}`);
+
+  try {
+    // Format the message using the module
+    const formattedMessage = formatMessage(
+      event.message_options.recipient,
+      event.message_options.text
+    );
+    console.log('Formatted message:', formattedMessage);
+
+    // Example: Make an API call to external service
+    const response = await axios.post('https://api.example.com/sms/send', {
+      to: formattedMessage.recipient,
+      body: formattedMessage.message,
+      trackingId: formattedMessage.id
+    });
+
+    console.log('Message sent successfully:', response.data);
+  } catch (error) {
+    console.error('Error sending phone message:', error.message);
+    // Allow the message to continue even if external API fails
+  }
+};

examples/directory/config.json.example

@@ -10,7 +10,8 @@
       "client_secret": "<add M2M client_secret>",
       "domain": "<add M2M domain>",
       "type": "OAUTH_APP"
-    }
+    },
+    "JWT_SECRET": "<your-jwt-secret-key>"
   },
   "AUTH0_ALLOW_DELETE": false,
   "INCLUDED_PROPS": {

examples/yaml/README.md

@@ -3,7 +3,7 @@
 This README will document how to use the YAML Option of the Auth0-deploy-cli tool. Please refer to the main project [README.md](../../README.md) for more information on the Auth0 Deploy CLI.
 
 # Overview
-The YAML option supports exporting and importing the Auth0 tenant configuration via a YAML file.
+The YAML option supports exporting and importing the Auth0 tenant configuration via a YAML file. This includes support for all resource types such as clients, connections, rules, actions, action modules, and more.
 
 For more information on YAML please refer to [http://yaml.org/](http://yaml.org/)
 

examples/yaml/action-modules/auth-helper/code.js

@@ -0,0 +1,32 @@
+const jwt = require('jsonwebtoken');
+const axios = require('axios');
+
+/**
+ * Auth Helper Module
+ * Provides JWT validation and token refresh utilities
+ */
+module.exports = {
+  /**
+   * Validates a JWT token
+   * @param {string} token - JWT token to validate
+   * @returns {Promise<object>} Decoded token payload
+   */
+  async validateToken(token) {
+    const secret = actions.secrets.JWT_SECRET;
+    try {
+      return jwt.verify(token, secret);
+    } catch (error) {
+      throw new Error('Invalid token: ' + error.message);
+    }
+  },
+
+  /**
+   * Fetches user data from an external API
+   * @param {string} userId - User ID to fetch
+   * @returns {Promise<object>} User data
+   */
+  async fetchUserData(userId) {
+    const response = await axios.get(`https://api.example.com/users/${userId}`);
+    return response.data;
+  }
+};