@friggframework/admin-scripts 2.0.0--canary.517.8eaf5df.0 → 2.0.0--canary.517.c197eb5.0

package/README.md

@@ -36,7 +36,6 @@ const Definition = {
     adminScripts: [AttioHealingScript],
 
     admin: {
-        includeBuiltinScripts: true, // register oauth-token-refresh + integration-health-check
         enableScheduling: true, // provision EventBridge Scheduler resources
     },
 };
@@ -44,7 +43,7 @@ const Definition = {
 module.exports = { Definition };
 ```
 
-At deploy time the framework's `AdminScriptBuilder` provisions the SQS queue, the router + worker Lambdas, and (when `enableScheduling` is set) the EventBridge Scheduler group and IAM role. At runtime the router/worker load this app definition and register your scripts (plus the built-ins) into the script registry.
+At deploy time the framework's `AdminScriptBuilder` provisions the SQS queue, the router + worker Lambdas, and (when `enableScheduling` is set) the EventBridge Scheduler group and IAM role. At runtime the router/worker load this app definition and register your scripts into the script registry.
 
 ---
 
@@ -96,9 +95,14 @@ class AttioHealingScript extends AdminScriptBase {
             throw new Error(`Integration ${integrationId} not found`);
         }
 
-        // Call the live integration/API when you need it
+        // Call the live integration when you need to hit an external API.
+        // Modules are attached to the instance by their own name (from the
+        // module's getName(), e.g. `instance.attio`) and each module's `.api`
+        // is its authenticated client. Iterate `instance.modules` if you don't
+        // want to hard-code a module name. The methods on `.api` are defined by
+        // that specific API module.
         const instance = await this.context.instantiate(integrationId);
-        await instance.primary.api.refreshMetadata();
+        await instance.attio.api.refreshEntityConfig(); // example — use your module's real method
 
         this.context.log('info', 'Healing complete', { integrationId });
         return { healed: true, integrationId };
@@ -159,10 +163,10 @@ curl -X POST https://<your-app>/admin/scripts/attio-healing \
 **Sync** — runs inline and returns the result. Only for fast scripts: in a deployed environment, sync is rejected (`400 SYNC_TIMEOUT_TOO_LONG`) when the script's `config.timeout` exceeds the API Lambda budget (~25s). Use `async` for anything longer.
 
 ```bash
-curl -X POST https://<your-app>/admin/scripts/integration-health-check \
+curl -X POST https://<your-app>/admin/scripts/attio-healing \
   -H "x-frigg-admin-api-key: $ADMIN_API_KEY" \
   -H "Content-Type: application/json" \
-  -d '{ "params": {}, "mode": "sync" }'
+  -d '{ "params": { "integrationId": "abc123" }, "mode": "sync" }'
 
 # 200 OK
 # { "executionId": "...", "status": "COMPLETED", "output": { ... }, "metrics": { "durationMs": 812 } }
@@ -203,29 +207,20 @@ A script can ship a default schedule in its `Definition.schedule`, and operators
 
 ```bash
 # Enable a daily 6am UTC run
-curl -X PUT https://<your-app>/admin/scripts/integration-health-check/schedule \
+curl -X PUT https://<your-app>/admin/scripts/attio-healing/schedule \
   -H "x-frigg-admin-api-key: $ADMIN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{ "enabled": true, "cronExpression": "cron(0 6 * * ? *)", "timezone": "UTC" }'
 
 # Inspect / remove
-curl https://<your-app>/admin/scripts/integration-health-check/schedule -H "x-frigg-admin-api-key: $ADMIN_API_KEY"
-curl -X DELETE https://<your-app>/admin/scripts/integration-health-check/schedule -H "x-frigg-admin-api-key: $ADMIN_API_KEY"
+curl https://<your-app>/admin/scripts/attio-healing/schedule -H "x-frigg-admin-api-key: $ADMIN_API_KEY"
+curl -X DELETE https://<your-app>/admin/scripts/attio-healing/schedule -H "x-frigg-admin-api-key: $ADMIN_API_KEY"
 ```
 
 Scheduling requires `admin.enableScheduling: true` in the app definition (so the EventBridge Scheduler group, IAM role, and env vars are provisioned). In a deployed environment the router refuses to fall back to the in-memory local scheduler, returning `503 SCHEDULER_NOT_CONFIGURED` if the provider isn't wired.
 
 ---
 
-## Built-in scripts
-
-Set `admin.includeBuiltinScripts: true` to register:
-
--   **`oauth-token-refresh`** — refreshes OAuth tokens for integrations nearing expiry. Params: `integrationIds?`, `expiryThresholdHours` (default 24), `dryRun`.
--   **`integration-health-check`** — checks credential validity and API connectivity. Params: `integrationIds?`, `checkCredentials` (default true), `checkConnectivity` (default true), `updateStatus` (default false).
-
----
-
 ## Script chaining
 
 Long or fan-out work can enqueue follow-up scripts. Continuations are tracked with `parentExecutionId` so you can trace the lineage:

package/index.js

@@ -37,14 +37,6 @@ const {
     handler: executorHandler,
 } = require('./src/infrastructure/script-executor-handler');
 
-// Built-in Scripts
-const {
-    OAuthTokenRefreshScript,
-    IntegrationHealthCheckScript,
-    builtinScripts,
-    registerBuiltinScripts,
-} = require('./src/builtins');
-
 // Adapters
 const { SchedulerAdapter } = require('./src/adapters/scheduler-adapter');
 const { AWSSchedulerAdapter } = require('./src/adapters/aws-scheduler-adapter');
@@ -76,12 +68,6 @@ module.exports = {
     routerHandler,
     executorHandler,
 
-    // Built-in scripts
-    OAuthTokenRefreshScript,
-    IntegrationHealthCheckScript,
-    builtinScripts,
-    registerBuiltinScripts,
-
     // Adapters
     SchedulerAdapter,
     AWSSchedulerAdapter,

package/package.json

@@ -1,18 +1,19 @@
 {
     "name": "@friggframework/admin-scripts",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.517.8eaf5df.0",
+    "version": "2.0.0--canary.517.c197eb5.0",
     "description": "Admin Script Runner for Frigg - Execute maintenance and operational scripts in hosted environments",
     "dependencies": {
         "@aws-sdk/client-scheduler": "^3.588.0",
-        "@friggframework/core": "2.0.0--canary.517.8eaf5df.0",
+        "@friggframework/core": "2.0.0--canary.517.c197eb5.0",
+        "@hapi/boom": "^10.0.1",
         "express": "^4.18.2",
         "serverless-http": "^3.2.0"
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.517.8eaf5df.0",
-        "@friggframework/prettier-config": "2.0.0--canary.517.8eaf5df.0",
-        "@friggframework/test": "2.0.0--canary.517.8eaf5df.0",
+        "@friggframework/eslint-config": "2.0.0--canary.517.c197eb5.0",
+        "@friggframework/prettier-config": "2.0.0--canary.517.c197eb5.0",
+        "@friggframework/test": "2.0.0--canary.517.c197eb5.0",
         "eslint": "^8.22.0",
         "jest": "^29.7.0",
         "prettier": "^2.7.1",
@@ -43,5 +44,5 @@
         "maintenance",
         "operations"
     ],
-    "gitHead": "8eaf5df0746c979fc5cb7877d51a861becd5fbce"
+    "gitHead": "c197eb5c237e263a8d1b65a94f213ee4732b3c57"
 }

package/src/application/use-cases/__tests__/delete-schedule-use-case.test.js

@@ -170,7 +170,7 @@ describe('DeleteScheduleUseCase', () => {
             try {
                 await useCase.execute('non-existent');
             } catch (error) {
-                expect(error.code).toBe('SCRIPT_NOT_FOUND');
+                expect(error.output.statusCode).toBe(404);
             }
         });
     });

package/src/application/use-cases/__tests__/get-effective-schedule-use-case.test.js

@@ -112,7 +112,7 @@ describe('GetEffectiveScheduleUseCase', () => {
             try {
                 await useCase.execute('non-existent');
             } catch (error) {
-                expect(error.code).toBe('SCRIPT_NOT_FOUND');
+                expect(error.output.statusCode).toBe(404);
             }
         });
     });

package/src/application/use-cases/__tests__/upsert-schedule-use-case.test.js

@@ -153,7 +153,7 @@ describe('UpsertScheduleUseCase', () => {
             try {
                 await useCase.execute('non-existent', { enabled: true });
             } catch (error) {
-                expect(error.code).toBe('SCRIPT_NOT_FOUND');
+                expect(error.output.statusCode).toBe(404);
             }
         });
 
@@ -167,7 +167,7 @@ describe('UpsertScheduleUseCase', () => {
             try {
                 await useCase.execute('test-script', { enabled: 'yes' });
             } catch (error) {
-                expect(error.code).toBe('INVALID_INPUT');
+                expect(error.output.statusCode).toBe(400);
             }
         });
 
@@ -183,7 +183,7 @@ describe('UpsertScheduleUseCase', () => {
             try {
                 await useCase.execute('test-script', { enabled: true });
             } catch (error) {
-                expect(error.code).toBe('INVALID_INPUT');
+                expect(error.output.statusCode).toBe(400);
             }
         });
 

package/src/application/use-cases/delete-schedule-use-case.js

@@ -1,3 +1,5 @@
+const Boom = require('@hapi/boom');
+
 /**
  * Delete Schedule Use Case
  *
@@ -51,9 +53,7 @@ class DeleteScheduleUseCase {
      */
     _validateScriptExists(scriptName) {
         if (!this.scriptFactory.has(scriptName)) {
-            const error = new Error(`Script "${scriptName}" not found`);
-            error.code = 'SCRIPT_NOT_FOUND';
-            throw error;
+            throw Boom.notFound(`Script "${scriptName}" not found`);
         }
     }
 

package/src/application/use-cases/get-effective-schedule-use-case.js

@@ -1,3 +1,5 @@
+const Boom = require('@hapi/boom');
+
 /**
  * Get Effective Schedule Use Case
  *
@@ -62,9 +64,7 @@ class GetEffectiveScheduleUseCase {
      */
     _validateScriptExists(scriptName) {
         if (!this.scriptFactory.has(scriptName)) {
-            const error = new Error(`Script "${scriptName}" not found`);
-            error.code = 'SCRIPT_NOT_FOUND';
-            throw error;
+            throw Boom.notFound(`Script "${scriptName}" not found`);
         }
     }
 

package/src/application/use-cases/upsert-schedule-use-case.js

@@ -1,3 +1,5 @@
+const Boom = require('@hapi/boom');
+
 /**
  * Upsert Schedule Use Case
  *
@@ -65,9 +67,7 @@ class UpsertScheduleUseCase {
      */
     _validateScriptExists(scriptName) {
         if (!this.scriptFactory.has(scriptName)) {
-            const error = new Error(`Script "${scriptName}" not found`);
-            error.code = 'SCRIPT_NOT_FOUND';
-            throw error;
+            throw Boom.notFound(`Script "${scriptName}" not found`);
         }
     }
 
@@ -76,17 +76,13 @@ class UpsertScheduleUseCase {
      */
     _validateInput(enabled, cronExpression) {
         if (typeof enabled !== 'boolean') {
-            const error = new Error('enabled must be a boolean');
-            error.code = 'INVALID_INPUT';
-            throw error;
+            throw Boom.badRequest('enabled must be a boolean');
         }
 
         if (enabled && !cronExpression) {
-            const error = new Error(
+            throw Boom.badRequest(
                 'cronExpression is required when enabled is true'
             );
-            error.code = 'INVALID_INPUT';
-            throw error;
         }
     }
 

package/src/infrastructure/__tests__/admin-script-router.test.js

@@ -404,7 +404,7 @@ describe('Admin Script Router', () => {
             );
 
             expect(response.status).toBe(404);
-            expect(response.body.code).toBe('SCRIPT_NOT_FOUND');
+            expect(response.body.error).toMatch(/not found/i);
         });
     });
 
@@ -481,7 +481,6 @@ describe('Admin Script Router', () => {
                 });
 
             expect(response.status).toBe(400);
-            expect(response.body.code).toBe('INVALID_INPUT');
             expect(response.body.error).toContain('enabled');
         });
 
@@ -493,7 +492,6 @@ describe('Admin Script Router', () => {
                 });
 
             expect(response.status).toBe(400);
-            expect(response.body.code).toBe('INVALID_INPUT');
             expect(response.body.error).toContain('cronExpression');
         });
 
@@ -508,7 +506,7 @@ describe('Admin Script Router', () => {
                 });
 
             expect(response.status).toBe(404);
-            expect(response.body.code).toBe('SCRIPT_NOT_FOUND');
+            expect(response.body.error).toMatch(/not found/i);
         });
 
         it('should provision EventBridge schedule when enabled', async () => {
@@ -712,7 +710,7 @@ describe('Admin Script Router', () => {
             );
 
             expect(response.status).toBe(404);
-            expect(response.body.code).toBe('SCRIPT_NOT_FOUND');
+            expect(response.body.error).toMatch(/not found/i);
         });
 
         it('should delete EventBridge schedule when external rule exists', async () => {

package/src/infrastructure/admin-script-router.js

@@ -1,5 +1,6 @@
 const express = require('express');
 const serverless = require('serverless-http');
+const Boom = require('@hapi/boom');
 const { validateAdminApiKey } = require('./admin-auth-middleware');
 const { getScriptFactory } = require('../application/script-factory');
 const { createScriptRunner } = require('../application/script-runner');
@@ -26,13 +27,27 @@ const router = express.Router();
 // Apply auth middleware to all admin routes
 router.use(validateAdminApiKey);
 
-// Register the host app's admin scripts (and built-ins) before handling requests.
+// Register the host app's admin scripts before handling requests.
 // Memoized, so this only does work on the first request per process.
 router.use((_req, _res, next) => {
     bootstrapAdminScripts();
     next();
 });
 
+/**
+ * Translate a thrown error into an HTTP response. Boom errors (thrown by the
+ * schedule use cases) carry their own status code; anything else is an
+ * unexpected 500. Mirrors the framework's app-handler-helpers convention.
+ * @private
+ */
+function sendError(res, error, fallbackMessage) {
+    if (error.isBoom) {
+        return res.status(error.output.statusCode).json({ error: error.message });
+    }
+    console.error(fallbackMessage, error);
+    return res.status(500).json({ error: fallbackMessage });
+}
+
 /**
  * Build audit metadata for an execution from the request.
  * @private
@@ -62,11 +77,9 @@ function createScheduleUseCases() {
         process.env.SCHEDULER_PROVIDER ||
         (process.env.AWS_LAMBDA_FUNCTION_NAME ? null : 'local');
     if (!schedulerType) {
-        const error = new Error(
+        throw Boom.serverUnavailable(
             'SCHEDULER_PROVIDER is not configured. Set it (e.g. "aws") via appDefinition.admin.enableScheduling.'
         );
-        error.code = 'SCHEDULER_NOT_CONFIGURED';
-        throw error;
     }
 
     const schedulerAdapter = createSchedulerAdapter({
@@ -354,19 +367,7 @@ router.get('/scripts/:scriptName/schedule', async (req, res) => {
             ...result.schedule,
         });
     } catch (error) {
-        if (error.code === 'SCRIPT_NOT_FOUND') {
-            return res.status(404).json({
-                error: error.message,
-                code: error.code,
-            });
-        }
-        if (error.code === 'SCHEDULER_NOT_CONFIGURED') {
-            return res
-                .status(503)
-                .json({ error: error.message, code: error.code });
-        }
-        console.error('Error getting schedule:', error);
-        res.status(500).json({ error: 'Failed to get schedule' });
+        return sendError(res, error, 'Failed to get schedule');
     }
 });
 
@@ -397,25 +398,7 @@ router.put('/scripts/:scriptName/schedule', async (req, res) => {
             }),
         });
     } catch (error) {
-        if (error.code === 'SCRIPT_NOT_FOUND') {
-            return res.status(404).json({
-                error: error.message,
-                code: error.code,
-            });
-        }
-        if (error.code === 'INVALID_INPUT') {
-            return res.status(400).json({
-                error: error.message,
-                code: error.code,
-            });
-        }
-        if (error.code === 'SCHEDULER_NOT_CONFIGURED') {
-            return res
-                .status(503)
-                .json({ error: error.message, code: error.code });
-        }
-        console.error('Error updating schedule:', error);
-        res.status(500).json({ error: 'Failed to update schedule' });
+        return sendError(res, error, 'Failed to update schedule');
     }
 });
 
@@ -432,19 +415,7 @@ router.delete('/scripts/:scriptName/schedule', async (req, res) => {
 
         res.json(result);
     } catch (error) {
-        if (error.code === 'SCRIPT_NOT_FOUND') {
-            return res.status(404).json({
-                error: error.message,
-                code: error.code,
-            });
-        }
-        if (error.code === 'SCHEDULER_NOT_CONFIGURED') {
-            return res
-                .status(503)
-                .json({ error: error.message, code: error.code });
-        }
-        console.error('Error deleting schedule:', error);
-        res.status(500).json({ error: 'Failed to delete schedule' });
+        return sendError(res, error, 'Failed to delete schedule');
     }
 });
 

package/src/infrastructure/bootstrap.js

@@ -55,15 +55,10 @@ function bootstrapAdminScripts() {
         const {
             loadAppDefinition,
         } = require('@friggframework/core/handlers/app-definition-loader');
-        const { adminScripts = [], admin = {} } = loadAppDefinition();
+        const { adminScripts = [] } = loadAppDefinition();
 
         const factory = getScriptFactory();
         registerScripts(factory, adminScripts);
-
-        if (admin.includeBuiltinScripts) {
-            const { builtinScripts } = require('../builtins');
-            registerScripts(factory, builtinScripts);
-        }
     } catch (error) {
         console.error(
             '[admin-scripts] bootstrap: could not load app definition:',