@friggframework/core 2.0.0--canary.548.c8ae0ca.0 → 2.0.0--canary.545.c40eca4.0

package/package.json

@@ -1,12 +1,8 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.548.c8ae0ca.0",
+    "version": "2.0.0--canary.545.c40eca4.0",
     "dependencies": {
-        "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
-        "@aws-sdk/client-kms": "^3.588.0",
-        "@aws-sdk/client-lambda": "^3.714.0",
-        "@aws-sdk/client-sqs": "^3.588.0",
         "@hapi/boom": "^10.0.1",
         "bcryptjs": "^2.4.3",
         "body-parser": "^1.20.2",
@@ -19,6 +15,7 @@
         "express-async-handler": "^1.2.0",
         "form-data": "^4.0.0",
         "fs-extra": "^11.2.0",
+        "js-yaml": "^4.1.0",
         "lodash": "4.17.21",
         "lodash.get": "^4.4.2",
         "node-fetch": "^2.6.7",
@@ -38,9 +35,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.548.c8ae0ca.0",
-        "@friggframework/prettier-config": "2.0.0--canary.548.c8ae0ca.0",
-        "@friggframework/test": "2.0.0--canary.548.c8ae0ca.0",
+        "@friggframework/eslint-config": "2.0.0--canary.545.c40eca4.0",
+        "@friggframework/prettier-config": "2.0.0--canary.545.c40eca4.0",
+        "@friggframework/test": "2.0.0--canary.545.c40eca4.0",
         "@prisma/client": "^6.17.0",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -53,6 +50,7 @@
         "prettier": "^2.7.1",
         "prisma": "^6.17.0",
         "sinon": "^16.1.1",
+        "supertest": "^7.1.4",
         "typescript": "^5.0.2"
     },
     "scripts": {
@@ -80,5 +78,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "c8ae0ca7837ba8393e3617be15c941607627c16b"
+    "gitHead": "c40eca49e72472f0499b24ce709a655a7503727b"
 }

package/prisma-mongodb/schema.prisma

@@ -360,3 +360,90 @@ model WebsocketConnection {
   @@index([connectionId])
   @@map("WebsocketConnection")
 }
+
+// ============================================================================
+// ADMIN PROCESS MODELS
+// ============================================================================
+
+/// Admin process state machine
+enum AdminProcessState {
+  PENDING
+  RUNNING
+  COMPLETED
+  FAILED
+}
+
+/// Admin trigger types
+enum AdminTrigger {
+  MANUAL
+  SCHEDULED
+  QUEUE
+  WEBHOOK
+}
+
+/// Admin process tracking (like Process but without user/integration FK)
+/// Used for: admin scripts, db migrations, system maintenance tasks
+model AdminProcess {
+  id   String @id @default(auto()) @map("_id") @db.ObjectId
+  name String // e.g., "oauth-token-refresh", "db-migration-xyz"
+  type String // e.g., "ADMIN_SCRIPT", "DB_MIGRATION"
+
+  // State machine
+  state AdminProcessState @default(PENDING)
+
+  // Flexible storage (mirrors Process model pattern)
+  context Json @default("{}") // input, trigger, audit info, script version
+  results Json @default("{}") // output, logs, metrics, errors
+
+  // Hierarchy support
+  childProcesses  String[] @db.ObjectId
+  parentProcessId String?  @db.ObjectId
+
+  // Timestamps
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([name, createdAt(sort: Desc)])
+  @@index([state])
+  @@index([type])
+  @@map("AdminProcess")
+}
+
+/// Script scheduling configuration for hybrid scheduling (SQS + EventBridge)
+model ScriptSchedule {
+  id              String    @id @default(auto()) @map("_id") @db.ObjectId
+  scriptName      String    @unique
+  enabled         Boolean   @default(false)
+  cronExpression  String?
+  timezone        String    @default("UTC")
+  lastTriggeredAt DateTime?
+  nextTriggerAt   DateTime?
+
+  // External Scheduler (e.g., AWS EventBridge Scheduler)
+  externalScheduleId   String?
+  externalScheduleName String?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([enabled])
+  @@map("ScriptSchedule")
+}
+
+/// One-time scheduled jobs for poll-and-dispatch scheduling pattern.
+/// Used by providers without native one-time scheduling APIs (e.g., Netlify).
+/// A cron function queries for due jobs and dispatches them to a queue.
+model ScheduledJob {
+  id              String   @id @default(auto()) @map("_id") @db.ObjectId
+  scheduleName    String   @unique
+  scheduledAt     DateTime
+  queueResourceId String
+  payload         Json?
+  state           String   @default("PENDING")
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([state, scheduledAt])
+  @@map("ScheduledJob")
+}

package/prisma-postgresql/migrations/20260222000000_add_admin_process_and_script_schedule/migration.sql

@@ -0,0 +1,55 @@
+-- CreateEnum
+CREATE TYPE "AdminProcessState" AS ENUM ('PENDING', 'RUNNING', 'COMPLETED', 'FAILED');
+
+-- CreateEnum
+CREATE TYPE "AdminTrigger" AS ENUM ('MANUAL', 'SCHEDULED', 'QUEUE', 'WEBHOOK');
+
+-- CreateTable
+CREATE TABLE "AdminProcess" (
+    "id" SERIAL NOT NULL,
+    "name" TEXT NOT NULL,
+    "type" TEXT NOT NULL,
+    "state" "AdminProcessState" NOT NULL DEFAULT 'PENDING',
+    "context" JSONB NOT NULL DEFAULT '{}',
+    "results" JSONB NOT NULL DEFAULT '{}',
+    "parentProcessId" INTEGER,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "AdminProcess_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "ScriptSchedule" (
+    "id" SERIAL NOT NULL,
+    "scriptName" TEXT NOT NULL,
+    "enabled" BOOLEAN NOT NULL DEFAULT false,
+    "cronExpression" TEXT,
+    "timezone" TEXT NOT NULL DEFAULT 'UTC',
+    "lastTriggeredAt" TIMESTAMP(3),
+    "nextTriggerAt" TIMESTAMP(3),
+    "externalScheduleId" TEXT,
+    "externalScheduleName" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "ScriptSchedule_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "AdminProcess_name_createdAt_idx" ON "AdminProcess"("name", "createdAt" DESC);
+
+-- CreateIndex
+CREATE INDEX "AdminProcess_state_idx" ON "AdminProcess"("state");
+
+-- CreateIndex
+CREATE INDEX "AdminProcess_type_idx" ON "AdminProcess"("type");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "ScriptSchedule_scriptName_key" ON "ScriptSchedule"("scriptName");
+
+-- CreateIndex
+CREATE INDEX "ScriptSchedule_enabled_idx" ON "ScriptSchedule"("enabled");
+
+-- AddForeignKey
+ALTER TABLE "AdminProcess" ADD CONSTRAINT "AdminProcess_parentProcessId_fkey" FOREIGN KEY ("parentProcessId") REFERENCES "AdminProcess"("id") ON DELETE SET NULL ON UPDATE CASCADE;

package/prisma-postgresql/schema.prisma

@@ -343,3 +343,88 @@ model WebsocketConnection {
 
   @@index([connectionId])
 }
+
+// ============================================================================
+// ADMIN PROCESS MODELS
+// ============================================================================
+
+/// Admin process state machine
+enum AdminProcessState {
+  PENDING
+  RUNNING
+  COMPLETED
+  FAILED
+}
+
+/// Admin trigger types
+enum AdminTrigger {
+  MANUAL
+  SCHEDULED
+  QUEUE
+  WEBHOOK
+}
+
+/// Admin process tracking (like Process but without user/integration FK)
+/// Used for: admin scripts, db migrations, system maintenance tasks
+model AdminProcess {
+  id   Int    @id @default(autoincrement())
+  name String // e.g., "oauth-token-refresh", "db-migration-xyz"
+  type String // e.g., "ADMIN_SCRIPT", "DB_MIGRATION"
+
+  // State machine
+  state AdminProcessState @default(PENDING)
+
+  // Flexible storage (mirrors Process model pattern)
+  context Json @default("{}") // input, trigger, audit info, script version
+  results Json @default("{}") // output, logs, metrics, errors
+
+  // Hierarchy support - self-referential relation
+  parentProcessId Int?
+  parentProcess   AdminProcess?  @relation("AdminProcessHierarchy", fields: [parentProcessId], references: [id], onDelete: SetNull)
+  childProcesses  AdminProcess[] @relation("AdminProcessHierarchy")
+
+  // Timestamps
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([name, createdAt(sort: Desc)])
+  @@index([state])
+  @@index([type])
+}
+
+/// Script scheduling configuration for hybrid scheduling (SQS + EventBridge)
+model ScriptSchedule {
+  id              Int       @id @default(autoincrement())
+  scriptName      String    @unique
+  enabled         Boolean   @default(false)
+  cronExpression  String?
+  timezone        String    @default("UTC")
+  lastTriggeredAt DateTime?
+  nextTriggerAt   DateTime?
+
+  // External Scheduler (e.g., AWS EventBridge Scheduler)
+  externalScheduleId   String?
+  externalScheduleName String?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([enabled])
+}
+
+/// One-time scheduled jobs for poll-and-dispatch scheduling pattern.
+/// Used by providers without native one-time scheduling APIs (e.g., Netlify).
+/// A cron function queries for due jobs and dispatches them to a queue.
+model ScheduledJob {
+  id              Int       @id @default(autoincrement())
+  scheduleName    String    @unique
+  scheduledAt     DateTime
+  queueResourceId String
+  payload         Json?
+  state           String    @default("PENDING")
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([state, scheduledAt])
+}

package/providers/index.js

@@ -0,0 +1,13 @@
+const {
+    resolveProvider,
+    determineProviderName,
+    providerPackageName,
+    KNOWN_PROVIDERS,
+} = require('./resolve-provider');
+
+module.exports = {
+    resolveProvider,
+    determineProviderName,
+    providerPackageName,
+    KNOWN_PROVIDERS,
+};

package/providers/resolve-provider.js

@@ -0,0 +1,93 @@
+/**
+ * Provider Resolver
+ *
+ * Resolves a provider name from the appDefinition into the corresponding
+ * @friggframework/provider-{name} package. This is the bridge between
+ * `appDefinition.provider` and the provider plugin interface.
+ *
+ * Resolution order:
+ *   1. Explicit `providerName` argument
+ *   2. `appDefinition.provider`
+ *   3. `FRIGG_PROVIDER` environment variable
+ *   4. Default: 'aws'
+ *
+ * Package naming convention:
+ *   provider: 'netlify'  →  require('@friggframework/provider-netlify')
+ *   provider: 'aws'      →  require('@friggframework/provider-aws')
+ *
+ * @example
+ *   const provider = resolveProvider({ provider: 'netlify' });
+ *   // provider.name === 'netlify'
+ *   // provider.deploy(appDefinition, options)
+ *   // provider.createHandler(options)
+ *   // provider.QueueProvider  (class)
+ *   // etc.
+ */
+
+const KNOWN_PROVIDERS = ['aws', 'netlify'];
+
+/**
+ * Determine the provider name from available sources.
+ *
+ * @param {Object} [appDefinition] - Frigg app definition
+ * @param {string} [providerName] - Explicit override
+ * @returns {string} Provider name (e.g. 'netlify', 'aws')
+ */
+function determineProviderName(appDefinition, providerName) {
+    if (providerName) {
+        return providerName;
+    }
+    if (appDefinition?.provider) {
+        return appDefinition.provider;
+    }
+    if (process.env.FRIGG_PROVIDER) {
+        return process.env.FRIGG_PROVIDER;
+    }
+    return 'aws';
+}
+
+/**
+ * Resolve a provider name to a package name.
+ *
+ * @param {string} name - Provider name (e.g. 'netlify')
+ * @returns {string} npm package name (e.g. '@friggframework/provider-netlify')
+ */
+function providerPackageName(name) {
+    return `@friggframework/provider-${name}`;
+}
+
+/**
+ * Resolve and load the provider plugin for the given app definition.
+ *
+ * @param {Object} [appDefinition] - Frigg app definition (reads .provider)
+ * @param {Object} [options]
+ * @param {string} [options.provider] - Explicit provider name override
+ * @returns {Object} Provider plugin (conforms to the provider plugin interface)
+ * @throws {Error} If the provider package is not installed
+ */
+function resolveProvider(appDefinition, options = {}) {
+    const name = determineProviderName(appDefinition, options.provider);
+    const packageName = providerPackageName(name);
+
+    try {
+        return require(packageName);
+    } catch (error) {
+        if (error.code === 'MODULE_NOT_FOUND') {
+            const hint = KNOWN_PROVIDERS.includes(name)
+                ? `Install it with: npm install ${packageName}`
+                : `Is '${name}' a valid Frigg provider? Known providers: ${KNOWN_PROVIDERS.join(', ')}`;
+
+            throw new Error(
+                `Provider '${name}' specified in appDefinition but package '${packageName}' is not installed.\n  ${hint}`
+            );
+        }
+        throw error;
+    }
+}
+
+module.exports = {
+    resolveProvider,
+    determineProviderName,
+    providerPackageName,
+    KNOWN_PROVIDERS,
+};

package/queues/index.js

@@ -1,4 +1,23 @@
 const { QueuerUtil } = require('./queuer-util');
+const { QueueProvider } = require('./queue-provider');
+const { QueueClientInterface } = require('./queue-client-interface');
+const {
+    createQueueProvider,
+    determineProvider,
+    QUEUE_PROVIDERS,
+} = require('./queue-provider-factory');
+const {
+    NetlifyBackgroundProvider,
+    QStashQueueProvider,
+} = require('./providers');
+
 module.exports = {
     QueuerUtil,
+    QueueProvider,
+    QueueClientInterface,
+    createQueueProvider,
+    determineProvider,
+    QUEUE_PROVIDERS,
+    NetlifyBackgroundProvider,
+    QStashQueueProvider,
 };

package/queues/providers/index.js

@@ -0,0 +1,7 @@
+const { NetlifyBackgroundProvider } = require('./netlify-background-provider');
+const { QStashQueueProvider } = require('./qstash-queue-provider');
+
+module.exports = {
+    NetlifyBackgroundProvider,
+    QStashQueueProvider,
+};

package/queues/providers/netlify-background-provider.js

@@ -0,0 +1,76 @@
+/**
+ * Netlify Background Functions Queue Provider (Adapter)
+ *
+ * Uses Netlify Background Functions for async job processing.
+ * Background functions have a 15-minute execution limit and are triggered via HTTP POST.
+ * They return 202 immediately while processing continues.
+ *
+ * Queue ID format: The function name or URL path for the background function.
+ * Convention: function files named with '-background' suffix (e.g., 'worker-background.js')
+ *
+ * Limitations:
+ * - No built-in retry (must implement manually)
+ * - No dead-letter queue
+ * - No FIFO ordering guarantees
+ * - 15-minute max execution time
+ */
+const { QueueProvider } = require('../queue-provider');
+
+class NetlifyBackgroundProvider extends QueueProvider {
+    constructor(options = {}) {
+        super();
+        // Base URL for triggering background functions (e.g., https://mysite.netlify.app)
+        this.baseUrl = options.baseUrl || process.env.URL || '';
+    }
+
+    /**
+     * Send a message by invoking a Netlify Background Function via HTTP POST.
+     *
+     * @param {Object} message - Message payload
+     * @param {string} queueId - Background function path (e.g., '/.netlify/functions/worker-background')
+     */
+    async send(message, queueId) {
+        const url = `${this.baseUrl}${queueId}`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(message),
+        });
+
+        if (!response.ok && response.status !== 202) {
+            throw new Error(
+                `Failed to invoke background function at ${queueId}: ${response.status} ${response.statusText}`
+            );
+        }
+
+        return { status: response.status, queueId };
+    }
+
+    /**
+     * Send batch of messages sequentially (background functions are HTTP-triggered).
+     */
+    async batchSend(entries = [], queueId) {
+        const results = [];
+        for (const entry of entries) {
+            const result = await this.send(entry, queueId);
+            results.push(result);
+        }
+        return { results };
+    }
+
+    /**
+     * Parse Netlify Background Function event.
+     * Background functions receive the raw HTTP event body as the event.
+     */
+    parseEvent(event) {
+        const body =
+            typeof event.body === 'string'
+                ? JSON.parse(event.body)
+                : event.body;
+
+        // Background functions receive a single message per invocation
+        return [body];
+    }
+}
+
+module.exports = { NetlifyBackgroundProvider };

package/queues/providers/qstash-queue-provider.js

@@ -0,0 +1,122 @@
+/**
+ * QStash Queue Provider (Adapter)
+ *
+ * Upstash QStash implementation - platform-agnostic HTTP-based message queue.
+ * Works on any platform (Netlify, Vercel, AWS, bare metal, etc.)
+ *
+ * Features:
+ * - Configurable retry with exponential backoff
+ * - Dead-letter queue via callbacks
+ * - At-least-once delivery
+ * - Scheduling support (delay, cron)
+ * - Message deduplication
+ *
+ * Requires:
+ * - QSTASH_TOKEN env var (from Upstash console)
+ * - QSTASH_CURRENT_SIGNING_KEY and QSTASH_NEXT_SIGNING_KEY for verification
+ *
+ * Queue ID format: The destination URL that QStash will POST to when delivering the message.
+ */
+const { QueueProvider } = require('../queue-provider');
+
+const QSTASH_API_BASE = 'https://qstash.upstash.io/v2';
+
+class QStashQueueProvider extends QueueProvider {
+    constructor(options = {}) {
+        super();
+        this.token =
+            options.token || process.env.QSTASH_TOKEN;
+        this.retries =
+            options.retries !== undefined ? options.retries : 3;
+    }
+
+    /**
+     * Send a message via QStash.
+     *
+     * @param {Object} message - Message payload
+     * @param {string} queueId - Destination URL that QStash will POST to
+     */
+    async send(message, queueId) {
+        if (!this.token) {
+            throw new Error(
+                'QSTASH_TOKEN is required. Get one at https://console.upstash.com'
+            );
+        }
+
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            'Content-Type': 'application/json',
+            'Upstash-Retries': String(this.retries),
+        };
+
+        const response = await fetch(
+            `${QSTASH_API_BASE}/publish/${queueId}`,
+            {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(message),
+            }
+        );
+
+        if (!response.ok) {
+            const errorBody = await response.text().catch(() => 'unknown');
+            throw new Error(
+                `QStash publish failed: ${response.status} ${response.statusText} - ${errorBody}`
+            );
+        }
+
+        return response.json();
+    }
+
+    /**
+     * Send batch of messages via QStash batch API.
+     */
+    async batchSend(entries = [], queueId) {
+        if (!this.token) {
+            throw new Error(
+                'QSTASH_TOKEN is required. Get one at https://console.upstash.com'
+            );
+        }
+
+        const messages = entries.map((entry) => ({
+            destination: queueId,
+            body: JSON.stringify(entry),
+            headers: { 'Content-Type': 'application/json' },
+            retries: this.retries,
+        }));
+
+        const response = await fetch(`${QSTASH_API_BASE}/batch`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(messages),
+        });
+
+        if (!response.ok) {
+            const errorBody = await response.text().catch(() => 'unknown');
+            throw new Error(
+                `QStash batch publish failed: ${response.status} - ${errorBody}`
+            );
+        }
+
+        return response.json();
+    }
+
+    /**
+     * Parse QStash webhook delivery event.
+     * QStash POSTs the message body directly to the destination URL.
+     */
+    parseEvent(event) {
+        const body =
+            typeof event.body === 'string'
+                ? JSON.parse(event.body)
+                : event.body;
+
+        // QStash delivers a single message per invocation
+        return [body];
+    }
+}
+
+module.exports = { QStashQueueProvider };

package/queues/queue-client-interface.js

@@ -0,0 +1,55 @@
+/**
+ * Queue Client Interface (Port)
+ *
+ * Defines the contract for low-level queue message operations.
+ * Used by Worker class and QueuerUtil for sending/receiving queue messages.
+ *
+ * Following Frigg's hexagonal architecture pattern:
+ * - Port defines WHAT the service does (contract)
+ * - Adapters implement HOW (AWS SQS, Netlify, QStash, etc.)
+ *
+ * Distinct from QueueProvider which is the higher-level provider for
+ * integration-level queue operations (send/batchSend/parseEvent).
+ * QueueClientInterface is the lower-level "how do I talk to the queue service" port.
+ */
+class QueueClientInterface {
+    /**
+     * Send a single message to a queue
+     *
+     * @param {Object} params
+     * @param {string} params.QueueUrl - Queue endpoint/identifier
+     * @param {string} params.MessageBody - Serialized message body
+     * @param {number} [params.DelaySeconds] - Delay before message becomes visible
+     * @returns {Promise<{MessageId: string}>} Result with message identifier
+     */
+    async sendMessage(params) {
+        throw new Error('Method sendMessage must be implemented by subclass');
+    }
+
+    /**
+     * Send a batch of messages to a queue
+     *
+     * @param {Object} params
+     * @param {string} params.QueueUrl - Queue endpoint/identifier
+     * @param {Array<{Id: string, MessageBody: string}>} params.Entries - Messages to send
+     * @returns {Promise<Object>} Batch send result
+     */
+    async sendMessageBatch(params) {
+        throw new Error(
+            'Method sendMessageBatch must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Resolve a queue name to a URL/endpoint
+     *
+     * @param {Object} params
+     * @param {string} params.QueueName - Queue name to resolve
+     * @returns {Promise<string>} Resolved queue URL/endpoint
+     */
+    async getQueueUrl(params) {
+        throw new Error('Method getQueueUrl must be implemented by subclass');
+    }
+}
+
+module.exports = { QueueClientInterface };