Imported from forter/forter-magento2 (AGENTS.md). Install upstream with npx skills add forter/forter-magento2. Copyright stays with the author.

forter-magento2

This file provides context for AI coding assistants working with this repository.

Repository Overview

This repository contains the Magento 2 Forter Fraud Detection Module. It integrates Forter's fraud prevention capabilities into Magento 2 e-commerce platforms.

Tech Stack: PHP, HTML, JavaScript

Build System

The project uses Magento 2's build system. Key commands include:

php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento cache:flush

Essential Workflows

Initial Setup

1. Install via composer (recommended):

   composer require forter/magento2-module-forter
   

2. Or install manually:

   • Place contents under {MAGENTO2-ROOT-DIR}/app/code/Forter/Forter

3. Run setup commands:

   php bin/magento maintenance:enable
   php bin/magento setup:upgrade
   php bin/magento setup:di:compile
   php bin/magento setup:static-content:deploy
   php bin/magento maintenance:disable
   php bin/magento cache:flush
   

Making Code Changes

1. Make changes in the appropriate directories (e.g., Block, Controller, Model)
2. Run compilation and deployment commands
3. Test changes thoroughly
4. Flush cache

Running Tests

No specific test commands are provided in the given context. Follow Magento 2 testing best practices.

Project Structure

📁 Block/                 # View-related classes
  📁 Adminhtml/           # Admin-specific blocks
  📁 Widget/              # Custom widgets
📁 Controller/            # Request handling
  📁 Callback/
  📁 Index/
📁 Cron/                  # Scheduled tasks
📁 Helper/                # Utility classes
📁 Logger/                # Custom logging
📁 Model/                 # Business logic and data
  📁 ActionsHandler/      # Handling approve/decline actions
  📁 Config/
  📁 Mappers/             # Payment gateway mappers
  📁 Order/
  📁 RequestBuilder/      # Building Forter API requests
  📁 ResourceModel/       # Database interactions
  📁 RmaFactory/
  📁 ThirdParty/          # Integrations with 3rd party services
📁 Observer/              # Event observers
📁 Plugin/                # Magento plugins for various components

Critical Patterns

1. Use of Mappers (Model/Mappers/) for different payment gateways
2. Request builders (Model/RequestBuilder/) for constructing API calls
3. Observers (Observer/) for various Magento events
4. Custom logging implementation (Logger/)
5. Cron jobs for queue processing and post-decision actions

Common Pitfalls to Avoid

1. Ensure proper error handling in API interactions
2. Be cautious with payment gateway integrations
3. Handle cron jobs efficiently to avoid performance issues
4. Properly sanitize and validate all inputs, especially in controllers

Security Guidelines (CRITICAL - Forter Standards)

Must Follow:

• ❌ NEVER hardcode secrets, API keys, or credentials
• ❌ NEVER log sensitive data (PII, tokens, passwords)
• ❌ NEVER commit .env files or secrets
• ✅ Use environment variables for all secrets
• ✅ Validate and sanitize all user inputs
• ✅ Follow the principle of least privilege

Additional Guidelines:

• Ensure all API calls use HTTPS
• Implement proper access controls for admin functionality
• Regularly update dependencies to patch security vulnerabilities

Before Committing

1. Run Magento 2 code sniffer
2. Ensure all new code has appropriate unit tests
3. Verify that no sensitive information is being logged
4. Run full Magento 2 test suite if available
5. Perform manual testing on key workflows

Generated by Forter AI Platform