@friggframework/core 2.0.0-next.11 → 2.0.0-next.110

package/application/commands/user-commands.js

@@ -0,0 +1,312 @@
+const {
+    createUserRepository,
+} = require('../../user/repositories/user-repository-factory');
+
+const ERROR_CODE_MAP = {
+    USER_NOT_FOUND: 404,
+    USER_ALREADY_EXISTS: 409,
+    INVALID_USER_DATA: 400,
+};
+
+function mapErrorToResponse(error) {
+    const status = ERROR_CODE_MAP[error?.code] || 500;
+    return {
+        error: status,
+        reason: error?.message,
+        code: error?.code,
+    };
+}
+
+/**
+ * Create user command factory
+ *
+ * NOTE: This is an internal API. Integration developers should use createFriggCommands() instead.
+ *
+ * @returns {Object} User command object with CRUD operations
+ */
+function createUserCommands() {
+    const userRepository = createUserRepository();
+
+    return {
+        /**
+         * Create a new individual user
+         * @param {Object} params
+         * @param {string} params.username - Username (usually email)
+         * @param {string} [params.email] - Email address
+         * @param {string} [params.appUserId] - External application user ID
+         * @param {string} [params.password] - Password (optional)
+         * @returns {Promise<Object>} Created user object
+         */
+        async createUser({ username, email, appUserId, password } = {}) {
+            try {
+                if (!username) {
+                    const error = new Error('username is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const userData = { username };
+                if (email) userData.email = email;
+                if (appUserId) userData.appUserId = appUserId;
+                if (password) userData.password = password;
+
+                const user = await userRepository.createIndividualUser(
+                    userData
+                );
+
+                return {
+                    id: user.id,
+                    username: user.username,
+                    email: user.email,
+                    appUserId: user.appUserId,
+                };
+            } catch (error) {
+                if (error.code === 11000) {
+                    // Duplicate key error
+                    const duplicateError = new Error(
+                        `User with username '${username}' already exists`
+                    );
+                    duplicateError.code = 'USER_ALREADY_EXISTS';
+                    return mapErrorToResponse(duplicateError);
+                }
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Find a user by their application user ID
+         * @param {string} appUserId - External application user ID
+         * @returns {Promise<Object|null>} User object or null if not found
+         */
+        async findUserByAppUserId(appUserId) {
+            try {
+                if (!appUserId) {
+                    const error = new Error('appUserId is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const user = await userRepository.findIndividualUserByAppUserId(
+                    appUserId
+                );
+
+                if (!user) {
+                    return null;
+                }
+
+                return {
+                    id: user.id,
+                    username: user.username,
+                    email: user.email,
+                    appUserId: user.appUserId,
+                };
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Find a user by their username
+         * @param {string} username - Username to search for
+         * @returns {Promise<Object|null>} User object or null if not found
+         */
+        async findUserByUsername(username) {
+            try {
+                if (!username) {
+                    const error = new Error('username is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const user = await userRepository.findIndividualUserByUsername(
+                    username
+                );
+
+                if (!user) {
+                    return null;
+                }
+
+                return {
+                    id: user.id,
+                    username: user.username,
+                    email: user.email,
+                    appUserId: user.appUserId,
+                };
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Find an individual user by their ID
+         * @param {string} userId - Individual user ID to search for
+         * @returns {Promise<Object|null>} Individual user object or null if not found
+         */
+        async findIndividualUserById(userId) {
+            try {
+                if (!userId) {
+                    const error = new Error('userId is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const user = await userRepository.findIndividualUserById(
+                    userId
+                );
+
+                if (!user) {
+                    return null;
+                }
+
+                return {
+                    id: user._id?.toString() || user.id,
+                    username: user.username,
+                    email: user.email,
+                    appUserId: user.appUserId,
+                };
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Find all individual users linked to an organization user
+         * @param {string} organizationUserId - Organization user ID to search for
+         * @returns {Promise<Object[]>} Array of individual user objects (empty if none)
+         */
+        async findIndividualUsersByOrganizationId(organizationUserId) {
+            try {
+                if (!organizationUserId) {
+                    const error = new Error('organizationUserId is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const users =
+                    await userRepository.findIndividualUsersByOrganizationId(
+                        organizationUserId
+                    );
+
+                return (users || []).map((user) => ({
+                    id: user._id?.toString() || user.id,
+                    username: user.username,
+                    email: user.email,
+                    appUserId: user.appUserId,
+                }));
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Find an organization user by their ID
+         * @param {string} userId - Organization user ID to search for
+         * @returns {Promise<Object|null>} Organization user object or null if not found
+         */
+        async findOrganizationUserById(userId) {
+            try {
+                if (!userId) {
+                    const error = new Error('userId is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const user = await userRepository.findOrganizationUserById(
+                    userId
+                );
+
+                if (!user) {
+                    return null;
+                }
+
+                return {
+                    id: user.id,
+                    appOrgId: user.appOrgId,
+                    name: user.name,
+                };
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Update a user by ID
+         * @param {string} userId - User ID to update
+         * @param {Object} updates - Fields to update
+         * @returns {Promise<Object>} Updated user object
+         */
+        async updateUser(userId, updates) {
+            try {
+                if (!userId) {
+                    const error = new Error('userId is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const user = await userRepository.IndividualUser.update(
+                    userId,
+                    updates
+                );
+
+                if (!user) {
+                    const error = new Error(`User ${userId} not found`);
+                    error.code = 'USER_NOT_FOUND';
+                    throw error;
+                }
+
+                return {
+                    id: user._id.toString(),
+                    username: user.username,
+                    email: user.email,
+                    appUserId: user.appUserId,
+                };
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        /**
+         * Delete a user by ID
+         *
+         * IMPORTANT: This does NOT automatically cascade delete related records in MongoDB.
+         * Integration developers MUST manually delete related data first:
+         * 1. Delete integrations (via deleteIntegrationById)
+         * 2. Delete entities (via deleteEntityById)
+         * 3. Delete credentials (via deleteCredentialById)
+         * 4. Finally delete user (via deleteUserById)
+         *
+         * @param {string} userId - User ID to delete
+         * @returns {Promise<Object>} Deletion result
+         */
+        async deleteUserById(userId) {
+            try {
+                if (!userId) {
+                    const error = new Error('userId is required');
+                    error.code = 'INVALID_USER_DATA';
+                    throw error;
+                }
+
+                const deleted = await userRepository.deleteUser(userId);
+
+                if (!deleted) {
+                    const error = new Error(`User ${userId} not found`);
+                    error.code = 'USER_NOT_FOUND';
+                    return mapErrorToResponse(error);
+                }
+
+                return {
+                    success: true,
+                    userId,
+                    message: 'User deleted successfully',
+                };
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+    };
+}
+
+module.exports = {
+    createUserCommands,
+    ERROR_CODE_MAP,
+};

package/application/index.js

@@ -0,0 +1,83 @@
+const {
+    createIntegrationCommands,
+    findIntegrationContextByExternalEntityId,
+} = require('./commands/integration-commands');
+const { createUserCommands } = require('./commands/user-commands');
+const { createEntityCommands } = require('./commands/entity-commands');
+const { createCredentialCommands } = require('./commands/credential-commands');
+const { createProcessCommands } = require('./commands/process-commands');
+const { createSchedulerCommands } = require('./commands/scheduler-commands');
+const { createUsageCommands } = require('./commands/usage-commands');
+
+/**
+ * Create a unified command factory with all CRUD operations
+ *
+ * This is the main entry point for integration developers to access all
+ * database operations without directly touching Mongoose models.
+ *
+ * @param {Object} params
+ * @param {Object} params.integrationClass - Integration class (required)
+ * @returns {Object} Unified commands object with all CRUD operations
+ *
+ * @example
+ * const commands = createFriggCommands({ integrationClass: MyIntegration });
+ * const user = await commands.createUser({ username: 'user@example.com' });
+ * const credential = await commands.createCredential({ userId: user.id, ... });
+ */
+function createFriggCommands({ integrationClass }) {
+    // All commands use Frigg's default repositories and use cases
+    const integrationCommands = createIntegrationCommands({ integrationClass });
+
+    const userCommands = createUserCommands();
+
+    const entityCommands = createEntityCommands();
+
+    const credentialCommands = createCredentialCommands();
+
+    const processCommands = createProcessCommands();
+
+    return {
+        // Integration commands
+        ...integrationCommands,
+
+        // User commands
+        ...userCommands,
+
+        // Entity commands
+        ...entityCommands,
+
+        // Credential commands
+        ...credentialCommands,
+
+        // Process commands
+        ...processCommands,
+
+        // Usage read/write — nested to match `frigg.usage.*`. The North Star
+        // read takes its config as a call argument, so nothing telemetry-specific
+        // is threaded through this general factory.
+        usage: createUsageCommands(),
+    };
+}
+
+module.exports = {
+    // Unified factory
+    createFriggCommands,
+
+    // Individual factories
+    createIntegrationCommands,
+    createUserCommands,
+    createEntityCommands,
+    createCredentialCommands,
+    createProcessCommands,
+    createSchedulerCommands,
+    createUsageCommands,
+
+    // Legacy standalone function
+    findIntegrationContextByExternalEntityId,
+
+    // Deprecated - use createFriggCommands instead
+    integrationCommands: {
+        create: createIntegrationCommands,
+        findIntegrationContextByExternalEntityId,
+    },
+};

package/artifacts/repositories/artifact-repository-factory.js

@@ -0,0 +1,19 @@
+// A configured bucket always wins, even in dev (unlike the encryption stage-bypass):
+// a deployed Lambda writes artifacts and the router reads them in different containers,
+// so routing dev to ephemeral /tmp would silently lose them.
+const { ArtifactRepositoryS3 } = require('./artifact-repository-s3');
+const { ArtifactRepositoryLocal } = require('./artifact-repository-local');
+
+function createArtifactRepository() {
+    const bucket = process.env.REPORT_ARTIFACT_BUCKET;
+    if (bucket) {
+        return new ArtifactRepositoryS3({ bucket });
+    }
+    return new ArtifactRepositoryLocal();
+}
+
+module.exports = {
+    createArtifactRepository,
+    ArtifactRepositoryS3,
+    ArtifactRepositoryLocal,
+};

package/artifacts/repositories/artifact-repository-interface.js

@@ -0,0 +1,27 @@
+/**
+ * Port for report artifacts (non-JSON output like CSV, PDF). Implementations
+ * write bytes to a durable store and return a location reference the caller
+ * persists; signed URLs are minted on read.
+ */
+class ArtifactRepositoryInterface {
+    /**
+     * @param {string} key - Caller-supplied, e.g. `reports/{executionId}/{name}-{stamp}.{ext}`.
+     * @returns {Promise<{bucket: string, key: string}>} Location reference.
+     */
+    async put(key, body, contentType) {
+        throw new Error('ArtifactRepositoryInterface.put not implemented');
+    }
+
+    /**
+     * @param {{bucket: string, key: string}|string} ref - Reference from put(), or a bare key.
+     */
+    async signedUrl(ref, { expiresIn } = {}) {
+        throw new Error('ArtifactRepositoryInterface.signedUrl not implemented');
+    }
+
+    async get(key) {
+        throw new Error('ArtifactRepositoryInterface.get not implemented');
+    }
+}
+
+module.exports = { ArtifactRepositoryInterface };

package/artifacts/repositories/artifact-repository-local.js

@@ -0,0 +1,42 @@
+/**
+ * Dev/test artifact adapter: writes to a local directory and returns file:// URLs.
+ * Selected by the factory only when no object store is configured (no REPORT_ARTIFACT_BUCKET).
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const {
+    ArtifactRepositoryInterface,
+} = require('./artifact-repository-interface');
+
+class ArtifactRepositoryLocal extends ArtifactRepositoryInterface {
+    constructor({ baseDir } = {}) {
+        super();
+        this.baseDir =
+            baseDir ||
+            process.env.REPORT_ARTIFACT_DIR ||
+            path.join(os.tmpdir(), 'frigg-report-artifacts');
+    }
+
+    _pathFor(key) {
+        return path.join(this.baseDir, key);
+    }
+
+    async put(key, body, _contentType) {
+        const filePath = this._pathFor(key);
+        await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.promises.writeFile(filePath, body);
+        return { bucket: this.baseDir, key };
+    }
+
+    async signedUrl(ref, _options = {}) {
+        const key = ref?.key || ref;
+        return `file://${this._pathFor(key)}`;
+    }
+
+    async get(key) {
+        return fs.promises.readFile(this._pathFor(key), 'utf8');
+    }
+}
+
+module.exports = { ArtifactRepositoryLocal };

package/artifacts/repositories/artifact-repository-s3.js

@@ -0,0 +1,61 @@
+// aws-sdk modules are lazy-required so importing this file (and the factory that
+// references it) never forces the SDK to load for contexts that only need the local adapter.
+const {
+    ArtifactRepositoryInterface,
+} = require('./artifact-repository-interface');
+
+class ArtifactRepositoryS3 extends ArtifactRepositoryInterface {
+    constructor({ bucket, region, s3Client } = {}) {
+        super();
+        this.bucket = bucket || process.env.REPORT_ARTIFACT_BUCKET;
+        this.region = region || process.env.AWS_REGION || 'us-east-1';
+        this._s3Client = s3Client || null;
+    }
+
+    _getClient() {
+        if (!this._s3Client) {
+            const { S3Client } = require('@aws-sdk/client-s3');
+            this._s3Client = new S3Client({ region: this.region });
+        }
+        return this._s3Client;
+    }
+
+    async put(key, body, contentType) {
+        if (!this.bucket) {
+            throw new Error(
+                'REPORT_ARTIFACT_BUCKET is not configured; cannot store report artifact'
+            );
+        }
+        const { PutObjectCommand } = require('@aws-sdk/client-s3');
+        // No ACL set: the bucket blocks public access, so objects stay private.
+        await this._getClient().send(
+            new PutObjectCommand({
+                Bucket: this.bucket,
+                Key: key,
+                Body: body,
+                ContentType: contentType,
+                ServerSideEncryption: 'AES256',
+            })
+        );
+        return { bucket: this.bucket, key };
+    }
+
+    async signedUrl(ref, { expiresIn = 3600 } = {}) {
+        const { GetObjectCommand } = require('@aws-sdk/client-s3');
+        const { getSignedUrl } = require('@aws-sdk/s3-request-presigner');
+        const bucket = ref?.bucket || this.bucket;
+        const key = ref?.key || ref;
+        const command = new GetObjectCommand({ Bucket: bucket, Key: key });
+        return getSignedUrl(this._getClient(), command, { expiresIn });
+    }
+
+    async get(key) {
+        const { GetObjectCommand } = require('@aws-sdk/client-s3');
+        const response = await this._getClient().send(
+            new GetObjectCommand({ Bucket: this.bucket, Key: key })
+        );
+        return response.Body.transformToString();
+    }
+}
+
+module.exports = { ArtifactRepositoryS3 };

package/assertions/index.js

@@ -6,10 +6,7 @@ const {
     getArrayParamAndVerifyParamType,
     getAndVerifyType,
 } = require('./get');
-const { expectShallowEqualDbObject } = require('./is-equal');
-
 module.exports = {
-    expectShallowEqualDbObject,
     get,
     getAll,
     verifyType,