@friggframework/core 2.0.0--canary.679.a2bcc2f.0 → 2.0.0--canary.686.87e9875.0

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,29 @@
 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,
+    get SqsQueueProvider() {
+        return require('./providers/sqs-queue-provider').SqsQueueProvider;
+    },
+    get SqsQueueClient() {
+        return require('./sqs-queue-client').SqsQueueClient;
+    },
 };

package/queues/providers/index.js

@@ -0,0 +1,11 @@
+const { NetlifyBackgroundProvider } = require('./netlify-background-provider');
+const { QStashQueueProvider } = require('./qstash-queue-provider');
+
+module.exports = {
+    NetlifyBackgroundProvider,
+    QStashQueueProvider,
+    // Lazy: requiring the barrel must not construct anything AWS-specific.
+    get SqsQueueProvider() {
+        return require('./sqs-queue-provider').SqsQueueProvider;
+    },
+};

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/providers/sqs-queue-provider.js

@@ -0,0 +1,61 @@
+/**
+ * SQS Queue Provider (Adapter)
+ *
+ * AWS SQS implementation of the QueueProvider port, from
+ * friggframework/frigg#545 (where it lives in @friggframework/provider-aws).
+ * Kept in core here because the AWS SDK is still a core dependency; the SDK
+ * is required on first send, not at module load.
+ */
+const { v4: uuid } = require('uuid');
+const { QueueProvider } = require('../queue-provider');
+const {
+    SqsQueueClient,
+    defaultSqsClientConfig,
+} = require('../sqs-queue-client');
+
+const SQS_BATCH_SIZE = 10;
+
+class SqsQueueProvider extends QueueProvider {
+    /**
+     * @param {Object} [options]
+     * @param {QueueClientInterface} [options.queueClient] - defaults to an SqsQueueClient.
+     */
+    constructor({ queueClient } = {}) {
+        super();
+        this.queueClient =
+            queueClient ||
+            new SqsQueueClient({ clientConfig: defaultSqsClientConfig() });
+    }
+
+    async send(message, queueUrl) {
+        return this.queueClient.sendMessage({
+            MessageBody: JSON.stringify(message),
+            QueueUrl: queueUrl,
+        });
+    }
+
+    async batchSend(entries = [], queueUrl) {
+        let last = {};
+        for (let i = 0; i < entries.length; i += SQS_BATCH_SIZE) {
+            const Entries = entries.slice(i, i + SQS_BATCH_SIZE).map((entry) => ({
+                Id: uuid(),
+                MessageBody: JSON.stringify(entry),
+            }));
+            last = await this.queueClient.sendMessageBatch({
+                Entries,
+                QueueUrl: queueUrl,
+            });
+        }
+        return last;
+    }
+
+    /**
+     * Parse an SQS event: event.Records[].body (JSON string).
+     */
+    parseEvent(event) {
+        const records = event?.Records || [];
+        return records.map((record) => JSON.parse(record.body));
+    }
+}
+
+module.exports = { SqsQueueProvider };

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 };

package/queues/queue-provider-factory.js

@@ -0,0 +1,101 @@
+/**
+ * Queue Provider Factory
+ *
+ * Creates a QueueProvider (send / batchSend / parseEvent) for the active
+ * platform. From friggframework/frigg#545, adapted: #545 resolved every
+ * provider through resolveProvider(), so an AWS app had to install
+ * @friggframework/provider-aws. In this stack the AWS SDK is a core
+ * dependency, so the built-in queues are created here and only an unknown
+ * name goes through the provider plugin system.
+ *
+ * Priority order for determining the provider:
+ * 1. Explicit `provider` option
+ * 2. `appDefinition.queue.provider`
+ * 3. `QUEUE_PROVIDER` environment variable
+ * 4. Default: SQS
+ *
+ * Built-in names:
+ * - 'sqs' | 'aws'                     -> SqsQueueProvider
+ * - 'netlify-background' | 'netlify'  -> NetlifyBackgroundProvider
+ * - 'qstash'                          -> QStashQueueProvider
+ * Any other name -> require('@friggframework/provider-<name>').QueueProvider
+ */
+
+const QUEUE_PROVIDERS = {
+    SQS: 'sqs',
+    NETLIFY_BACKGROUND: 'netlify-background',
+    QSTASH: 'qstash',
+};
+
+// Platform provider names (appDefinition.provider) that map to a built-in queue.
+const PLATFORM_ALIASES = {
+    aws: QUEUE_PROVIDERS.SQS,
+    netlify: QUEUE_PROVIDERS.NETLIFY_BACKGROUND,
+};
+
+/**
+ * Determine the queue provider from the config hierarchy.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.provider]
+ * @param {Object} [options.appDefinition]
+ * @returns {string|undefined}
+ */
+function determineProvider(options = {}) {
+    if (options.provider) {
+        return options.provider;
+    }
+    if (options.appDefinition?.queue?.provider) {
+        return options.appDefinition.queue.provider;
+    }
+    if (process.env.QUEUE_PROVIDER) {
+        return process.env.QUEUE_PROVIDER;
+    }
+    return undefined;
+}
+
+/**
+ * Create a queue provider instance.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.provider] - Queue provider name
+ * @param {Object} [options.appDefinition] - reads `queue.provider`
+ * @param {Object} [options.providerOptions] - passed to the provider constructor
+ * @returns {import('./queue-provider').QueueProvider}
+ */
+function createQueueProvider(options = {}) {
+    const explicit = determineProvider(options);
+    const name = PLATFORM_ALIASES[explicit] || explicit || QUEUE_PROVIDERS.SQS;
+    const providerOptions = options.providerOptions || {};
+
+    switch (name) {
+        case QUEUE_PROVIDERS.SQS: {
+            const { SqsQueueProvider } = require('./providers/sqs-queue-provider');
+            return new SqsQueueProvider(providerOptions);
+        }
+        case QUEUE_PROVIDERS.NETLIFY_BACKGROUND: {
+            const {
+                NetlifyBackgroundProvider,
+            } = require('./providers/netlify-background-provider');
+            return new NetlifyBackgroundProvider(providerOptions);
+        }
+        case QUEUE_PROVIDERS.QSTASH: {
+            const { QStashQueueProvider } = require('./providers/qstash-queue-provider');
+            return new QStashQueueProvider(providerOptions);
+        }
+        default: {
+            const { resolveProvider } = require('../providers/resolve-provider');
+            const provider = resolveProvider(null, { provider: name });
+            if (!provider.QueueProvider) {
+                throw new Error(`Provider '${provider.name || name}' does not export a QueueProvider`);
+            }
+            return new provider.QueueProvider(providerOptions);
+        }
+    }
+}
+
+module.exports = {
+    createQueueProvider,
+    determineProvider,
+    QUEUE_PROVIDERS,
+};

package/queues/queue-provider.js

@@ -0,0 +1,46 @@
+/**
+ * Queue Provider Interface (Port)
+ *
+ * Defines the contract for queue message sending.
+ * All queue adapters must extend this interface.
+ *
+ * Following Frigg's hexagonal architecture pattern:
+ * - Port defines WHAT the service does (contract)
+ * - Adapters implement HOW (AWS SQS, Netlify Background Functions, QStash, etc.)
+ */
+class QueueProvider {
+    /**
+     * Send a single message to a queue
+     *
+     * @param {Object} message - Message payload (will be JSON-serialized)
+     * @param {string} queueId - Queue identifier (URL, name, or endpoint depending on provider)
+     * @returns {Promise<Object>} Provider-specific response
+     */
+    async send(message, queueId) {
+        throw new Error('Method send must be implemented by subclass');
+    }
+
+    /**
+     * Send a batch of messages to a queue
+     *
+     * @param {Object[]} entries - Array of message payloads
+     * @param {string} queueId - Queue identifier
+     * @returns {Promise<Object>} Provider-specific response
+     */
+    async batchSend(entries, queueId) {
+        throw new Error('Method batchSend must be implemented by subclass');
+    }
+
+    /**
+     * Parse an incoming event into an array of message payloads.
+     * Each provider has its own event shape (SQS Records, HTTP body, etc.)
+     *
+     * @param {Object} event - Raw event from the runtime (Lambda event, HTTP request, etc.)
+     * @returns {Object[]} Array of parsed message payloads
+     */
+    parseEvent(event) {
+        throw new Error('Method parseEvent must be implemented by subclass');
+    }
+}
+
+module.exports = { QueueProvider };

package/queues/sqs-queue-client.js

@@ -0,0 +1,81 @@
+/**
+ * SQS Queue Client (Adapter)
+ *
+ * AWS SQS implementation of QueueClientInterface, used by Worker.
+ *
+ * In friggframework/frigg#545 this adapter moved to
+ * @friggframework/provider-aws and Worker required it to be injected. In
+ * this stack the AWS SDK stays a core dependency, so the adapter lives here,
+ * Worker defaults to it, and provider-aws re-exports it. The SDK is
+ * required on first use, not at module load.
+ */
+const { QueueClientInterface } = require('./queue-client-interface');
+
+let sqsModule = null;
+function getSqsModule() {
+    if (!sqsModule) {
+        sqsModule = require('@aws-sdk/client-sqs');
+    }
+    return sqsModule;
+}
+
+/**
+ * Client config #545's adapter used: IS_OFFLINE credentials, AWS_REGION and
+ * AWS_ENDPOINT.
+ */
+function defaultSqsClientConfig() {
+    const config = {};
+    if (process.env.IS_OFFLINE) {
+        config.credentials = {
+            accessKeyId: 'test-aws-key',
+            secretAccessKey: 'test-aws-secret',
+        };
+        config.region = 'us-east-1';
+    }
+    if (!config.region && process.env.AWS_REGION) {
+        config.region = process.env.AWS_REGION;
+    }
+    if (process.env.AWS_ENDPOINT) {
+        config.endpoint = process.env.AWS_ENDPOINT;
+    }
+    return config;
+}
+
+class SqsQueueClient extends QueueClientInterface {
+    /**
+     * @param {Object} [options]
+     * @param {Object} [options.clientConfig] - SQSClient config; defaults to
+     *   defaultSqsClientConfig().
+     */
+    constructor({ clientConfig } = {}) {
+        super();
+        this._clientConfig = clientConfig;
+        this._sqs = null;
+    }
+
+    _client() {
+        if (!this._sqs) {
+            const { SQSClient } = getSqsModule();
+            this._sqs = new SQSClient(this._clientConfig || defaultSqsClientConfig());
+        }
+        return this._sqs;
+    }
+
+    async sendMessage(params) {
+        const { SendMessageCommand } = getSqsModule();
+        return this._client().send(new SendMessageCommand(params));
+    }
+
+    async sendMessageBatch(params) {
+        const { SendMessageBatchCommand } = getSqsModule();
+        return this._client().send(new SendMessageBatchCommand(params));
+    }
+
+    async getQueueUrl(params) {
+        const { GetQueueUrlCommand } = getSqsModule();
+        const data = await this._client().send(new GetQueueUrlCommand(params));
+        return data.QueueUrl;
+    }
+}
+
+module.exports = { SqsQueueClient, defaultSqsClientConfig };

package/types/index.d.ts

@@ -12,4 +12,5 @@
 /// <reference path="./eslint-config/index.d.ts" />
 /// <reference path="./associations/index.d.ts" />
 /// <reference path="./syncs/index.d.ts" />
+/// <reference path="./user/index.d.ts" />
 /// <reference path="./modules/index.d.ts" />