@friggframework/admin-scripts 2.0.0--canary.517.41839c5.0

package/src/application/admin-frigg-commands.js

@@ -0,0 +1,242 @@
+const { QueuerUtil } = require('@friggframework/core/queues');
+
+/**
+ * AdminFriggCommands
+ *
+ * Helper API for admin scripts. Provides:
+ * - Database access via repositories
+ * - Integration instantiation (optional)
+ * - Logging utilities
+ * - Queue operations for self-queuing pattern
+ *
+ * Follows lazy-loading pattern for repositories to avoid circular dependencies
+ * and unnecessary initialization.
+ */
+class AdminFriggCommands {
+    constructor(params = {}) {
+        this.executionId = params.executionId || null;
+        this.logs = [];
+
+        // OPTIONAL: Integration factory for scripts that need external API access
+        this.integrationFactory = params.integrationFactory || null;
+
+        // Lazy-load repositories to avoid circular deps
+        this._integrationRepository = null;
+        this._userRepository = null;
+        this._moduleRepository = null;
+        this._credentialRepository = null;
+        this._scriptExecutionRepository = null;
+    }
+
+    // ==================== LAZY-LOADED REPOSITORIES ====================
+
+    get integrationRepository() {
+        if (!this._integrationRepository) {
+            const { createIntegrationRepository } = require('@friggframework/core/integrations/repositories/integration-repository-factory');
+            this._integrationRepository = createIntegrationRepository();
+        }
+        return this._integrationRepository;
+    }
+
+    get userRepository() {
+        if (!this._userRepository) {
+            const { createUserRepository } = require('@friggframework/core/user/repositories/user-repository-factory');
+            this._userRepository = createUserRepository();
+        }
+        return this._userRepository;
+    }
+
+    get moduleRepository() {
+        if (!this._moduleRepository) {
+            const { createModuleRepository } = require('@friggframework/core/modules/repositories/module-repository-factory');
+            this._moduleRepository = createModuleRepository();
+        }
+        return this._moduleRepository;
+    }
+
+    get credentialRepository() {
+        if (!this._credentialRepository) {
+            const { createCredentialRepository } = require('@friggframework/core/credential/repositories/credential-repository-factory');
+            this._credentialRepository = createCredentialRepository();
+        }
+        return this._credentialRepository;
+    }
+
+    get scriptExecutionRepository() {
+        if (!this._scriptExecutionRepository) {
+            const { createScriptExecutionRepository } = require('@friggframework/core/admin-scripts/repositories/script-execution-repository-factory');
+            this._scriptExecutionRepository = createScriptExecutionRepository();
+        }
+        return this._scriptExecutionRepository;
+    }
+
+    // ==================== INTEGRATION QUERIES ====================
+
+    async listIntegrations(filter = {}) {
+        if (filter.userId) {
+            return this.integrationRepository.findIntegrationsByUserId(filter.userId);
+        }
+        return this.integrationRepository.findIntegrations(filter);
+    }
+
+    async findIntegrationById(id) {
+        return this.integrationRepository.findIntegrationById(id);
+    }
+
+    async findIntegrationsByUserId(userId) {
+        return this.integrationRepository.findIntegrationsByUserId(userId);
+    }
+
+    async updateIntegrationConfig(integrationId, config) {
+        return this.integrationRepository.updateIntegrationConfig(integrationId, config);
+    }
+
+    async updateIntegrationStatus(integrationId, status) {
+        return this.integrationRepository.updateIntegrationStatus(integrationId, status);
+    }
+
+    // ==================== USER QUERIES ====================
+
+    async findUserById(userId) {
+        return this.userRepository.findIndividualUserById(userId);
+    }
+
+    async findUserByAppUserId(appUserId) {
+        return this.userRepository.findIndividualUserByAppUserId(appUserId);
+    }
+
+    async findUserByUsername(username) {
+        return this.userRepository.findIndividualUserByUsername(username);
+    }
+
+    // ==================== ENTITY QUERIES ====================
+
+    async listEntities(filter = {}) {
+        if (filter.userId) {
+            return this.moduleRepository.findEntitiesByUserId(filter.userId);
+        }
+        return this.moduleRepository.findEntity(filter);
+    }
+
+    async findEntityById(entityId) {
+        return this.moduleRepository.findEntityById(entityId);
+    }
+
+    // ==================== CREDENTIAL QUERIES ====================
+
+    async findCredential(filter) {
+        return this.credentialRepository.findCredential(filter);
+    }
+
+    async updateCredential(credentialId, updates) {
+        return this.credentialRepository.updateCredential(credentialId, updates);
+    }
+
+    // ==================== INTEGRATION INSTANTIATION ====================
+
+    /**
+     * Instantiate an integration instance (for calling external APIs)
+     * REQUIRES: integrationFactory in constructor
+     */
+    async instantiate(integrationId) {
+        if (!this.integrationFactory) {
+            throw new Error(
+                'instantiate() requires integrationFactory. ' +
+                'Set Definition.config.requiresIntegrationFactory = true'
+            );
+        }
+        return this.integrationFactory.getInstanceFromIntegrationId({
+            integrationId,
+            _isAdminContext: true,  // Bypass user ownership check
+        });
+    }
+
+    // ==================== QUEUE OPERATIONS (Self-Queuing Pattern) ====================
+
+    /**
+     * Queue a script for execution
+     * Used for self-queuing pattern with long-running scripts
+     */
+    async queueScript(scriptName, params = {}) {
+        const queueUrl = process.env.ADMIN_SCRIPT_QUEUE_URL;
+        if (!queueUrl) {
+            throw new Error('ADMIN_SCRIPT_QUEUE_URL environment variable not set');
+        }
+
+        await QueuerUtil.send(
+            {
+                scriptName,
+                trigger: 'QUEUE',
+                params,
+                parentExecutionId: this.executionId,
+            },
+            queueUrl
+        );
+
+        this.log('info', `Queued continuation for ${scriptName}`, { params });
+    }
+
+    /**
+     * Queue multiple scripts in a batch
+     */
+    async queueScriptBatch(entries) {
+        const queueUrl = process.env.ADMIN_SCRIPT_QUEUE_URL;
+        if (!queueUrl) {
+            throw new Error('ADMIN_SCRIPT_QUEUE_URL environment variable not set');
+        }
+
+        const messages = entries.map(entry => ({
+            scriptName: entry.scriptName,
+            trigger: 'QUEUE',
+            params: entry.params || {},
+            parentExecutionId: this.executionId,
+        }));
+
+        await QueuerUtil.batchSend(messages, queueUrl);
+        this.log('info', `Queued ${entries.length} script continuations`);
+    }
+
+    // ==================== LOGGING ====================
+
+    log(level, message, data = {}) {
+        const entry = {
+            level,
+            message,
+            data,
+            timestamp: new Date().toISOString(),
+        };
+        this.logs.push(entry);
+
+        // Persist to execution record if we have an executionId
+        if (this.executionId) {
+            this.scriptExecutionRepository.appendExecutionLog(this.executionId, entry)
+                .catch(err => console.error('Failed to persist log:', err));
+        }
+
+        return entry;
+    }
+
+    getExecutionId() {
+        return this.executionId;
+    }
+
+    getLogs() {
+        return this.logs;
+    }
+
+    clearLogs() {
+        this.logs = [];
+    }
+}
+
+/**
+ * Create AdminFriggCommands instance
+ */
+function createAdminFriggCommands(params = {}) {
+    return new AdminFriggCommands(params);
+}
+
+module.exports = {
+    AdminFriggCommands,
+    createAdminFriggCommands,
+};

package/src/application/admin-script-base.js

@@ -0,0 +1,138 @@
+const { createScriptExecutionRepository } = require('@friggframework/core/admin-scripts/repositories/script-execution-repository-factory');
+const { createAdminApiKeyRepository } = require('@friggframework/core/admin-scripts/repositories/admin-api-key-repository-factory');
+
+/**
+ * Admin Script Base Class
+ *
+ * Base class for all admin scripts. Provides:
+ * - Standard script definition pattern
+ * - Repository access
+ * - Logging helpers
+ * - Integration factory support (optional)
+ *
+ * Usage:
+ * ```javascript
+ * class MyScript extends AdminScriptBase {
+ *   static Definition = {
+ *     name: 'my-script',
+ *     version: '1.0.0',
+ *     description: 'Does something useful',
+ *     ...
+ *   };
+ *
+ *   async execute(frigg, params) {
+ *     // Your script logic here
+ *   }
+ * }
+ * ```
+ */
+class AdminScriptBase {
+    /**
+     * CHILDREN SHOULD SPECIFY A DEFINITION FOR THE SCRIPT
+     * Pattern matches IntegrationBase.Definition
+     */
+    static Definition = {
+        name: 'Script Name', // Required: unique identifier
+        version: '0.0.0', // Required: semver for migrations
+        description: 'What this script does', // Required: human-readable
+
+        // Script-specific properties
+        source: 'USER_DEFINED', // 'BUILTIN' | 'USER_DEFINED'
+
+        inputSchema: null, // Optional: JSON Schema for params
+        outputSchema: null, // Optional: JSON Schema for results
+
+        schedule: {
+            // Optional: Phase 2
+            enabled: false,
+            cronExpression: null, // 'cron(0 12 * * ? *)'
+        },
+
+        config: {
+            timeout: 300000, // Default 5 min (ms)
+            maxRetries: 0,
+            requiresIntegrationFactory: false, // Hint: does script need to instantiate integrations?
+        },
+
+        display: {
+            // For future UI
+            label: 'Script Name',
+            description: '',
+            category: 'maintenance', // 'maintenance' | 'healing' | 'sync' | 'custom'
+        },
+    };
+
+    static getName() {
+        return this.Definition.name;
+    }
+
+    static getCurrentVersion() {
+        return this.Definition.version;
+    }
+
+    static getDefinition() {
+        return this.Definition;
+    }
+
+    /**
+     * Constructor receives dependencies
+     * Pattern matches IntegrationBase constructor
+     */
+    constructor(params = {}) {
+        this.executionId = params.executionId || null;
+        this.logs = [];
+        this._startTime = null;
+
+        // OPTIONAL: Integration factory for scripts that need it
+        this.integrationFactory = params.integrationFactory || null;
+
+        // OPTIONAL: Injected repositories (for testing or custom implementations)
+        this.scriptExecutionRepository = params.scriptExecutionRepository || null;
+        this.adminApiKeyRepository = params.adminApiKeyRepository || null;
+    }
+
+    /**
+     * CHILDREN MUST IMPLEMENT THIS METHOD
+     * @param {AdminFriggCommands} frigg - Helper commands object
+     * @param {Object} params - Script parameters (validated against inputSchema)
+     * @returns {Promise<Object>} - Script results (validated against outputSchema)
+     */
+    async execute(frigg, params) {
+        throw new Error('AdminScriptBase.execute() must be implemented by subclass');
+    }
+
+    /**
+     * Logging helper
+     * @param {string} level - Log level (info, warn, error, debug)
+     * @param {string} message - Log message
+     * @param {Object} data - Additional data
+     * @returns {Object} Log entry
+     */
+    log(level, message, data = {}) {
+        const entry = {
+            level,
+            message,
+            data,
+            timestamp: new Date().toISOString(),
+        };
+        this.logs.push(entry);
+        return entry;
+    }
+
+    /**
+     * Get all logs
+     * @returns {Array} Log entries
+     */
+    getLogs() {
+        return this.logs;
+    }
+
+    /**
+     * Clear all logs
+     */
+    clearLogs() {
+        this.logs = [];
+    }
+}
+
+module.exports = { AdminScriptBase };

package/src/application/dry-run-http-interceptor.js

@@ -0,0 +1,296 @@
+/**
+ * Dry-Run HTTP Interceptor
+ *
+ * Creates a mock HTTP client that logs requests instead of executing them.
+ * Used to intercept API module calls during dry-run.
+ */
+
+/**
+ * Sanitize headers to remove authentication tokens
+ * @param {Object} headers - HTTP headers
+ * @returns {Object} Sanitized headers
+ */
+function sanitizeHeaders(headers) {
+    if (!headers || typeof headers !== 'object') {
+        return {};
+    }
+
+    const safe = { ...headers };
+
+    // Remove common auth headers
+    const sensitiveHeaders = [
+        'authorization',
+        'Authorization',
+        'x-api-key',
+        'X-API-Key',
+        'x-auth-token',
+        'X-Auth-Token',
+        'api-key',
+        'API-Key',
+        'apikey',
+        'ApiKey',
+        'token',
+        'Token',
+    ];
+
+    for (const header of sensitiveHeaders) {
+        if (safe[header]) {
+            safe[header] = '[REDACTED]';
+        }
+    }
+
+    return safe;
+}
+
+/**
+ * Detect service name from base URL
+ * @param {string} baseURL - Base URL of the API
+ * @returns {string} Service name
+ */
+function detectService(baseURL) {
+    if (!baseURL) return 'unknown';
+
+    const url = baseURL.toLowerCase();
+
+    // CRM Systems
+    if (url.includes('hubspot') || url.includes('hubapi')) return 'HubSpot';
+    if (url.includes('salesforce')) return 'Salesforce';
+    if (url.includes('pipedrive')) return 'Pipedrive';
+    if (url.includes('zoho')) return 'Zoho CRM';
+    if (url.includes('attio')) return 'Attio';
+
+    // Communication
+    if (url.includes('slack')) return 'Slack';
+    if (url.includes('discord')) return 'Discord';
+    if (url.includes('teams.microsoft')) return 'Microsoft Teams';
+
+    // Project Management
+    if (url.includes('asana')) return 'Asana';
+    if (url.includes('monday')) return 'Monday.com';
+    if (url.includes('trello')) return 'Trello';
+    if (url.includes('clickup')) return 'ClickUp';
+
+    // Storage
+    if (url.includes('googleapis.com/drive')) return 'Google Drive';
+    if (url.includes('dropbox')) return 'Dropbox';
+    if (url.includes('box.com')) return 'Box';
+
+    // Email & Marketing
+    if (url.includes('sendgrid')) return 'SendGrid';
+    if (url.includes('mailchimp')) return 'Mailchimp';
+    if (url.includes('gmail')) return 'Gmail';
+
+    // Accounting
+    if (url.includes('quickbooks')) return 'QuickBooks';
+    if (url.includes('xero')) return 'Xero';
+
+    // Other
+    if (url.includes('stripe')) return 'Stripe';
+    if (url.includes('shopify')) return 'Shopify';
+    if (url.includes('github')) return 'GitHub';
+    if (url.includes('gitlab')) return 'GitLab';
+
+    return 'unknown';
+}
+
+/**
+ * Sanitize request data to remove sensitive information
+ * @param {*} data - Request data
+ * @returns {*} Sanitized data
+ */
+function sanitizeData(data) {
+    if (data === null || data === undefined) {
+        return data;
+    }
+
+    if (typeof data !== 'object') {
+        return data;
+    }
+
+    if (Array.isArray(data)) {
+        return data.map(sanitizeData);
+    }
+
+    const sanitized = {};
+    for (const [key, value] of Object.entries(data)) {
+        const lowerKey = key.toLowerCase();
+
+        // Check if this is a leaf node that should be redacted
+        const isSensitiveField =
+            lowerKey === 'password' ||
+            lowerKey === 'token' ||
+            lowerKey === 'secret' ||
+            lowerKey === 'apikey' ||
+            lowerKey.endsWith('password') ||
+            lowerKey.endsWith('token') ||
+            lowerKey.endsWith('secret') ||
+            lowerKey.endsWith('key') && !lowerKey.endsWith('publickey');
+
+        // Only redact if it's a primitive value (not an object/array)
+        if (isSensitiveField && typeof value !== 'object') {
+            sanitized[key] = '[REDACTED]';
+            continue;
+        }
+
+        // Recursively sanitize nested objects
+        if (typeof value === 'object' && value !== null) {
+            sanitized[key] = sanitizeData(value);
+        } else {
+            sanitized[key] = value;
+        }
+    }
+
+    return sanitized;
+}
+
+/**
+ * Create a dry-run HTTP client
+ *
+ * @param {Array} operationLog - Array to append logged HTTP requests
+ * @returns {Object} Mock HTTP client compatible with axios interface
+ */
+function createDryRunHttpClient(operationLog) {
+    /**
+     * Mock HTTP request handler
+     * @param {Object} config - Request configuration
+     * @returns {Promise<Object>} Mock response
+     */
+    const mockRequest = async (config) => {
+        // Build full URL
+        let fullUrl = config.url;
+        if (config.baseURL && !config.url.startsWith('http')) {
+            fullUrl = `${config.baseURL}${config.url.startsWith('/') ? '' : '/'}${config.url}`;
+        }
+
+        // Log the request that WOULD have been made
+        const logEntry = {
+            operation: 'HTTP_REQUEST',
+            method: (config.method || 'GET').toUpperCase(),
+            url: fullUrl,
+            baseURL: config.baseURL,
+            path: config.url,
+            service: detectService(config.baseURL || fullUrl),
+            headers: sanitizeHeaders(config.headers),
+            timestamp: new Date().toISOString(),
+        };
+
+        // Include request data for write operations
+        if (config.data && ['POST', 'PUT', 'PATCH'].includes(logEntry.method)) {
+            logEntry.data = sanitizeData(config.data);
+        }
+
+        // Include query params
+        if (config.params) {
+            logEntry.params = sanitizeData(config.params);
+        }
+
+        operationLog.push(logEntry);
+
+        // Return mock response
+        return {
+            status: 200,
+            statusText: 'OK (Dry-Run)',
+            data: {
+                _dryRun: true,
+                _message: 'This is a dry-run mock response',
+                _wouldHaveExecuted: `${logEntry.method} ${fullUrl}`,
+                _service: logEntry.service,
+            },
+            headers: {
+                'content-type': 'application/json',
+                'x-dry-run': 'true',
+            },
+            config,
+        };
+    };
+
+    // Return axios-compatible interface
+    return {
+        request: mockRequest,
+        get: (url, config = {}) => mockRequest({ ...config, method: 'GET', url }),
+        post: (url, data, config = {}) => mockRequest({ ...config, method: 'POST', url, data }),
+        put: (url, data, config = {}) => mockRequest({ ...config, method: 'PUT', url, data }),
+        patch: (url, data, config = {}) =>
+            mockRequest({ ...config, method: 'PATCH', url, data }),
+        delete: (url, config = {}) => mockRequest({ ...config, method: 'DELETE', url }),
+        head: (url, config = {}) => mockRequest({ ...config, method: 'HEAD', url }),
+        options: (url, config = {}) => mockRequest({ ...config, method: 'OPTIONS', url }),
+
+        // Axios-specific properties
+        defaults: {
+            headers: {
+                common: {},
+                get: {},
+                post: {},
+                put: {},
+                patch: {},
+                delete: {},
+            },
+        },
+
+        // Interceptors (no-op in dry-run)
+        interceptors: {
+            request: { use: () => {}, eject: () => {} },
+            response: { use: () => {}, eject: () => {} },
+        },
+    };
+}
+
+/**
+ * Inject dry-run HTTP client into an integration instance
+ *
+ * @param {Object} integrationInstance - Integration instance from integrationFactory
+ * @param {Object} dryRunHttpClient - Dry-run HTTP client
+ */
+function injectDryRunHttpClient(integrationInstance, dryRunHttpClient) {
+    if (!integrationInstance) {
+        return;
+    }
+
+    // Inject into primary API module
+    if (integrationInstance.primary?.api) {
+        injectIntoApiModule(integrationInstance.primary.api, dryRunHttpClient);
+    }
+
+    // Inject into target API module
+    if (integrationInstance.target?.api) {
+        injectIntoApiModule(integrationInstance.target.api, dryRunHttpClient);
+    }
+}
+
+/**
+ * Inject dry-run HTTP client into an API module
+ * @param {Object} apiModule - API module instance
+ * @param {Object} dryRunHttpClient - Dry-run HTTP client
+ */
+function injectIntoApiModule(apiModule, dryRunHttpClient) {
+    // Common property names for HTTP clients in API modules
+    const httpClientProps = [
+        '_httpClient',
+        'httpClient',
+        'client',
+        'axios',
+        'request',
+        'api',
+        'http',
+    ];
+
+    for (const prop of httpClientProps) {
+        if (apiModule[prop] && typeof apiModule[prop] === 'object') {
+            apiModule[prop] = dryRunHttpClient;
+        }
+    }
+
+    // Also check if the API module itself has request methods
+    if (typeof apiModule.request === 'function') {
+        Object.assign(apiModule, dryRunHttpClient);
+    }
+}
+
+module.exports = {
+    createDryRunHttpClient,
+    injectDryRunHttpClient,
+    sanitizeHeaders,
+    sanitizeData,
+    detectService,
+};