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

package/src/builtins/__tests__/oauth-token-refresh.test.js

@@ -0,0 +1,344 @@
+const { OAuthTokenRefreshScript } = require('../oauth-token-refresh');
+
+describe('OAuthTokenRefreshScript', () => {
+    describe('Definition', () => {
+        it('should have correct name and metadata', () => {
+            expect(OAuthTokenRefreshScript.Definition.name).toBe('oauth-token-refresh');
+            expect(OAuthTokenRefreshScript.Definition.version).toBe('1.0.0');
+            expect(OAuthTokenRefreshScript.Definition.source).toBe('BUILTIN');
+            expect(OAuthTokenRefreshScript.Definition.config.requiresIntegrationFactory).toBe(true);
+        });
+
+        it('should have valid input schema', () => {
+            const schema = OAuthTokenRefreshScript.Definition.inputSchema;
+            expect(schema.type).toBe('object');
+            expect(schema.properties.integrationIds).toBeDefined();
+            expect(schema.properties.expiryThresholdHours).toBeDefined();
+            expect(schema.properties.dryRun).toBeDefined();
+        });
+
+        it('should have valid output schema', () => {
+            const schema = OAuthTokenRefreshScript.Definition.outputSchema;
+            expect(schema.type).toBe('object');
+            expect(schema.properties.refreshed).toBeDefined();
+            expect(schema.properties.failed).toBeDefined();
+            expect(schema.properties.skipped).toBeDefined();
+            expect(schema.properties.details).toBeDefined();
+        });
+
+        it('should have appropriate timeout configuration', () => {
+            expect(OAuthTokenRefreshScript.Definition.config.timeout).toBe(600000); // 10 minutes
+        });
+    });
+
+    describe('execute()', () => {
+        let script;
+        let mockFrigg;
+
+        beforeEach(() => {
+            script = new OAuthTokenRefreshScript();
+            mockFrigg = {
+                log: jest.fn(),
+                listIntegrations: jest.fn(),
+                findIntegrationById: jest.fn(),
+                instantiate: jest.fn(),
+            };
+        });
+
+        it('should return empty results when no integrations found', async () => {
+            mockFrigg.listIntegrations.mockResolvedValue([]);
+
+            const result = await script.execute(mockFrigg, {});
+
+            expect(result.refreshed).toBe(0);
+            expect(result.failed).toBe(0);
+            expect(result.skipped).toBe(0);
+            expect(result.details).toEqual([]);
+            expect(mockFrigg.log).toHaveBeenCalledWith('info', expect.any(String), expect.any(Object));
+        });
+
+        it('should skip integrations without OAuth credentials', async () => {
+            const integration = {
+                id: 'int-1',
+                config: {} // No credentials
+            };
+            mockFrigg.listIntegrations.mockResolvedValue([integration]);
+
+            const result = await script.execute(mockFrigg, {});
+
+            expect(result.skipped).toBe(1);
+            expect(result.refreshed).toBe(0);
+            expect(result.details[0]).toMatchObject({
+                integrationId: 'int-1',
+                action: 'skipped',
+                reason: 'No OAuth credentials found'
+            });
+        });
+
+        it('should skip integrations without expiry time', async () => {
+            const integration = {
+                id: 'int-1',
+                config: {
+                    credentials: {
+                        access_token: 'token123'
+                        // No expires_at
+                    }
+                }
+            };
+            mockFrigg.listIntegrations.mockResolvedValue([integration]);
+
+            const result = await script.execute(mockFrigg, {});
+
+            expect(result.skipped).toBe(1);
+            expect(result.details[0]).toMatchObject({
+                integrationId: 'int-1',
+                action: 'skipped',
+                reason: 'No expiry time found'
+            });
+        });
+
+        it('should skip tokens not near expiry', async () => {
+            const farFutureExpiry = new Date(Date.now() + 48 * 60 * 60 * 1000); // 48 hours from now
+            const integration = {
+                id: 'int-1',
+                config: {
+                    credentials: {
+                        access_token: 'token123',
+                        expires_at: farFutureExpiry.toISOString()
+                    }
+                }
+            };
+            mockFrigg.listIntegrations.mockResolvedValue([integration]);
+
+            const result = await script.execute(mockFrigg, {
+                expiryThresholdHours: 24
+            });
+
+            expect(result.skipped).toBe(1);
+            expect(result.details[0]).toMatchObject({
+                integrationId: 'int-1',
+                action: 'skipped',
+                reason: 'Token not near expiry'
+            });
+        });
+
+        it('should refresh tokens that are near expiry', async () => {
+            const soonExpiry = new Date(Date.now() + 12 * 60 * 60 * 1000); // 12 hours from now
+            const integration = {
+                id: 'int-1',
+                config: {
+                    credentials: {
+                        access_token: 'token123',
+                        expires_at: soonExpiry.toISOString()
+                    }
+                }
+            };
+
+            const mockInstance = {
+                primary: {
+                    api: {
+                        refreshAccessToken: jest.fn().mockResolvedValue(undefined)
+                    }
+                }
+            };
+
+            mockFrigg.listIntegrations.mockResolvedValue([integration]);
+            mockFrigg.instantiate.mockResolvedValue(mockInstance);
+
+            const result = await script.execute(mockFrigg, {
+                expiryThresholdHours: 24
+            });
+
+            expect(result.refreshed).toBe(1);
+            expect(result.skipped).toBe(0);
+            expect(mockInstance.primary.api.refreshAccessToken).toHaveBeenCalled();
+            expect(result.details[0]).toMatchObject({
+                integrationId: 'int-1',
+                action: 'refreshed'
+            });
+        });
+
+        it('should handle dryRun mode correctly', async () => {
+            const soonExpiry = new Date(Date.now() + 12 * 60 * 60 * 1000);
+            const integration = {
+                id: 'int-1',
+                config: {
+                    credentials: {
+                        access_token: 'token123',
+                        expires_at: soonExpiry.toISOString()
+                    }
+                }
+            };
+
+            mockFrigg.listIntegrations.mockResolvedValue([integration]);
+
+            const result = await script.execute(mockFrigg, {
+                expiryThresholdHours: 24,
+                dryRun: true
+            });
+
+            expect(result.refreshed).toBe(0);
+            expect(result.skipped).toBe(1);
+            expect(mockFrigg.instantiate).not.toHaveBeenCalled();
+            expect(result.details[0]).toMatchObject({
+                integrationId: 'int-1',
+                action: 'skipped',
+                reason: 'Dry run - would have refreshed'
+            });
+        });
+
+        it('should handle refresh failures gracefully', async () => {
+            const soonExpiry = new Date(Date.now() + 12 * 60 * 60 * 1000);
+            const integration = {
+                id: 'int-1',
+                config: {
+                    credentials: {
+                        access_token: 'token123',
+                        expires_at: soonExpiry.toISOString()
+                    }
+                }
+            };
+
+            const mockInstance = {
+                primary: {
+                    api: {
+                        refreshAccessToken: jest.fn().mockRejectedValue(new Error('API Error'))
+                    }
+                }
+            };
+
+            mockFrigg.listIntegrations.mockResolvedValue([integration]);
+            mockFrigg.instantiate.mockResolvedValue(mockInstance);
+
+            const result = await script.execute(mockFrigg, {
+                expiryThresholdHours: 24
+            });
+
+            expect(result.failed).toBe(1);
+            expect(result.refreshed).toBe(0);
+            expect(result.details[0]).toMatchObject({
+                integrationId: 'int-1',
+                action: 'failed',
+                reason: 'API Error'
+            });
+        });
+
+        it('should skip integrations without refresh support', async () => {
+            const soonExpiry = new Date(Date.now() + 12 * 60 * 60 * 1000);
+            const integration = {
+                id: 'int-1',
+                config: {
+                    credentials: {
+                        access_token: 'token123',
+                        expires_at: soonExpiry.toISOString()
+                    }
+                }
+            };
+
+            const mockInstance = {
+                primary: {
+                    api: {
+                        // No refreshAccessToken method
+                    }
+                }
+            };
+
+            mockFrigg.listIntegrations.mockResolvedValue([integration]);
+            mockFrigg.instantiate.mockResolvedValue(mockInstance);
+
+            const result = await script.execute(mockFrigg, {
+                expiryThresholdHours: 24
+            });
+
+            expect(result.skipped).toBe(1);
+            expect(result.details[0]).toMatchObject({
+                integrationId: 'int-1',
+                action: 'skipped',
+                reason: 'API does not support token refresh'
+            });
+        });
+
+        it('should filter by specific integration IDs', async () => {
+            const integration1 = {
+                id: 'int-1',
+                config: { credentials: { access_token: 'token1' } }
+            };
+            const integration2 = {
+                id: 'int-2',
+                config: { credentials: { access_token: 'token2' } }
+            };
+
+            mockFrigg.findIntegrationById.mockImplementation((id) => {
+                if (id === 'int-1') return Promise.resolve(integration1);
+                if (id === 'int-2') return Promise.resolve(integration2);
+                return Promise.reject(new Error('Not found'));
+            });
+
+            const result = await script.execute(mockFrigg, {
+                integrationIds: ['int-1', 'int-2']
+            });
+
+            expect(mockFrigg.findIntegrationById).toHaveBeenCalledWith('int-1');
+            expect(mockFrigg.findIntegrationById).toHaveBeenCalledWith('int-2');
+            expect(mockFrigg.listIntegrations).not.toHaveBeenCalled();
+            expect(result.details).toHaveLength(2);
+        });
+
+        it('should handle errors when processing integrations', async () => {
+            const integration = {
+                id: 'int-1',
+                config: {
+                    credentials: {
+                        access_token: 'token123',
+                        expires_at: new Date(Date.now() + 12 * 60 * 60 * 1000).toISOString()
+                    }
+                }
+            };
+
+            mockFrigg.listIntegrations.mockResolvedValue([integration]);
+            mockFrigg.instantiate.mockRejectedValue(new Error('Instantiation failed'));
+
+            const result = await script.execute(mockFrigg, {
+                expiryThresholdHours: 24
+            });
+
+            expect(result.failed).toBe(1);
+            expect(result.details[0]).toMatchObject({
+                integrationId: 'int-1',
+                action: 'failed',
+                reason: 'Instantiation failed'
+            });
+        });
+    });
+
+    describe('processIntegration()', () => {
+        let script;
+        let mockFrigg;
+
+        beforeEach(() => {
+            script = new OAuthTokenRefreshScript();
+            mockFrigg = {
+                log: jest.fn(),
+                instantiate: jest.fn(),
+            };
+        });
+
+        it('should return correct detail object for each scenario', async () => {
+            // Test various scenarios are covered in execute() tests above
+            // This test validates the method can be called directly
+            const integration = {
+                id: 'int-1',
+                config: {}
+            };
+
+            const result = await script.processIntegration(mockFrigg, integration, {
+                expiryThresholdHours: 24,
+                dryRun: false
+            });
+
+            expect(result).toHaveProperty('integrationId');
+            expect(result).toHaveProperty('action');
+            expect(result).toHaveProperty('reason');
+        });
+    });
+});

package/src/builtins/index.js

@@ -0,0 +1,28 @@
+const { OAuthTokenRefreshScript } = require('./oauth-token-refresh');
+const { IntegrationHealthCheckScript } = require('./integration-health-check');
+
+/**
+ * Built-in Admin Scripts
+ *
+ * These scripts ship with @friggframework/admin-scripts and provide
+ * common maintenance and monitoring functionality.
+ */
+const builtinScripts = [
+    OAuthTokenRefreshScript,
+    IntegrationHealthCheckScript,
+];
+
+/**
+ * Register all built-in scripts with a factory
+ * @param {ScriptFactory} factory - Script factory to register with
+ */
+function registerBuiltinScripts(factory) {
+    factory.registerAll(builtinScripts);
+}
+
+module.exports = {
+    OAuthTokenRefreshScript,
+    IntegrationHealthCheckScript,
+    builtinScripts,
+    registerBuiltinScripts,
+};

package/src/builtins/integration-health-check.js

@@ -0,0 +1,279 @@
+const { AdminScriptBase } = require('../application/admin-script-base');
+
+/**
+ * Integration Health Check Script
+ *
+ * Checks the health of integrations by verifying:
+ * - Credential validity
+ * - API connectivity
+ * - Configuration integrity
+ */
+class IntegrationHealthCheckScript extends AdminScriptBase {
+    static Definition = {
+        name: 'integration-health-check',
+        version: '1.0.0',
+        description: 'Checks health of integrations and reports issues',
+        source: 'BUILTIN',
+
+        inputSchema: {
+            type: 'object',
+            properties: {
+                integrationIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Specific integration IDs to check (optional, defaults to all)'
+                },
+                checkCredentials: {
+                    type: 'boolean',
+                    default: true,
+                    description: 'Verify credential validity'
+                },
+                checkConnectivity: {
+                    type: 'boolean',
+                    default: true,
+                    description: 'Test API connectivity'
+                },
+                updateStatus: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'Update integration status based on health'
+                }
+            }
+        },
+
+        outputSchema: {
+            type: 'object',
+            properties: {
+                healthy: { type: 'number' },
+                unhealthy: { type: 'number' },
+                unknown: { type: 'number' },
+                results: { type: 'array' }
+            }
+        },
+
+        config: {
+            timeout: 900000, // 15 minutes
+            maxRetries: 0,
+            requiresIntegrationFactory: true,
+        },
+
+        schedule: {
+            enabled: false,  // Can be enabled via API
+            cronExpression: 'cron(0 6 * * ? *)', // Daily at 6 AM UTC
+        },
+
+        display: {
+            label: 'Integration Health Check',
+            description: 'Check health and connectivity of integrations',
+            category: 'maintenance',
+        },
+    };
+
+    async execute(frigg, params = {}) {
+        const {
+            integrationIds = null,
+            checkCredentials = true,
+            checkConnectivity = true,
+            updateStatus = false
+        } = params;
+
+        const summary = {
+            healthy: 0,
+            unhealthy: 0,
+            unknown: 0,
+            results: []
+        };
+
+        frigg.log('info', 'Starting integration health check', {
+            checkCredentials,
+            checkConnectivity,
+            updateStatus,
+            specificIds: integrationIds?.length || 'all'
+        });
+
+        // Get integrations to check
+        let integrations;
+        if (integrationIds && integrationIds.length > 0) {
+            integrations = await Promise.all(
+                integrationIds.map(id => frigg.findIntegrationById(id).catch(() => null))
+            );
+            integrations = integrations.filter(Boolean);
+        } else {
+            integrations = await this.getAllIntegrations(frigg);
+        }
+
+        frigg.log('info', `Checking ${integrations.length} integrations`);
+
+        for (const integration of integrations) {
+            const result = await this.checkIntegration(frigg, integration, {
+                checkCredentials,
+                checkConnectivity
+            });
+
+            summary.results.push(result);
+
+            if (result.status === 'healthy') {
+                summary.healthy++;
+            } else if (result.status === 'unhealthy') {
+                summary.unhealthy++;
+            } else {
+                summary.unknown++;
+            }
+
+            // Optionally update integration status
+            if (updateStatus && result.status !== 'unknown') {
+                try {
+                    const newStatus = result.status === 'healthy' ? 'ACTIVE' : 'ERROR';
+                    await frigg.updateIntegrationStatus(integration.id, newStatus);
+                    frigg.log('info', `Updated status for ${integration.id} to ${newStatus}`);
+                } catch (error) {
+                    frigg.log('warn', `Failed to update status for ${integration.id}`, {
+                        error: error.message
+                    });
+                }
+            }
+        }
+
+        frigg.log('info', 'Health check completed', {
+            healthy: summary.healthy,
+            unhealthy: summary.unhealthy,
+            unknown: summary.unknown
+        });
+
+        return summary;
+    }
+
+    async getAllIntegrations(frigg) {
+        return frigg.listIntegrations({});
+    }
+
+    async checkIntegration(frigg, integration, options) {
+        const { checkCredentials, checkConnectivity } = options;
+        const result = this._createCheckResult(integration);
+
+        try {
+            await this._runChecks(frigg, integration, result, { checkCredentials, checkConnectivity });
+            this._determineOverallStatus(result);
+        } catch (error) {
+            this._handleCheckError(frigg, integration, result, error);
+        }
+
+        return result;
+    }
+
+    /**
+     * Create initial check result object
+     * @private
+     */
+    _createCheckResult(integration) {
+        return {
+            integrationId: integration.id,
+            integrationType: integration.config?.type || 'unknown',
+            status: 'unknown',
+            checks: {},
+            issues: []
+        };
+    }
+
+    /**
+     * Run all requested checks
+     * @private
+     */
+    async _runChecks(frigg, integration, result, options) {
+        const { checkCredentials, checkConnectivity } = options;
+
+        if (checkCredentials) {
+            this._addCheckResult(result, 'credentials', this.checkCredentialValidity(integration));
+        }
+
+        if (checkConnectivity) {
+            this._addCheckResult(result, 'connectivity', await this.checkApiConnectivity(frigg, integration));
+        }
+    }
+
+    /**
+     * Add a check result and track any issues
+     * @private
+     */
+    _addCheckResult(result, checkName, checkResult) {
+        result.checks[checkName] = checkResult;
+        if (!checkResult.valid) {
+            result.issues.push(checkResult.issue);
+        }
+    }
+
+    /**
+     * Determine overall health status from issues
+     * @private
+     */
+    _determineOverallStatus(result) {
+        result.status = result.issues.length === 0 ? 'healthy' : 'unhealthy';
+    }
+
+    /**
+     * Handle check error and update result
+     * @private
+     */
+    _handleCheckError(frigg, integration, result, error) {
+        frigg.log('error', `Error checking integration ${integration.id}`, {
+            error: error.message
+        });
+        result.status = 'unknown';
+        result.issues.push(`Check failed: ${error.message}`);
+    }
+
+    checkCredentialValidity(integration) {
+        const result = { valid: true, issue: null };
+
+        // Check for access token
+        if (!integration.config?.credentials?.access_token) {
+            result.valid = false;
+            result.issue = 'Missing access token';
+            return result;
+        }
+
+        // Check for expiry
+        const expiresAt = integration.config?.credentials?.expires_at;
+        if (expiresAt) {
+            const expiryTime = new Date(expiresAt);
+            if (expiryTime < new Date()) {
+                result.valid = false;
+                result.issue = 'Access token expired';
+                return result;
+            }
+        }
+
+        return result;
+    }
+
+    async checkApiConnectivity(frigg, integration) {
+        const result = { valid: true, issue: null, responseTime: null };
+
+        try {
+            const startTime = Date.now();
+            const instance = await frigg.instantiate(integration.id);
+
+            // Try to make a simple API call
+            if (instance.primary?.api?.getAuthenticationInfo) {
+                await instance.primary.api.getAuthenticationInfo();
+            } else if (instance.primary?.api?.getCurrentUser) {
+                await instance.primary.api.getCurrentUser();
+            } else {
+                // No suitable health check method
+                result.valid = true;
+                result.issue = null;
+                result.note = 'No health check endpoint available';
+                return result;
+            }
+
+            result.responseTime = Date.now() - startTime;
+        } catch (error) {
+            result.valid = false;
+            result.issue = `API connectivity failed: ${error.message}`;
+        }
+
+        return result;
+    }
+}
+
+module.exports = { IntegrationHealthCheckScript };