Implement Ecreee e-tender plugin integration

docs/usage-guide/ecreee-e-tender-integration.md

@@ -0,0 +1,141 @@
+---
+order: 27
+---
+
+# ECREEE e-Tender Integration Setup Guide
+
+This guide provides step-by-step instructions to set up the integration between **MicroPowerManager (MPM)** and the **ECREEE e-Tender platform** for milestone-based progress tracking and disbursement verification.
+
+---
+
+## Overview
+
+The **ECREEE e-Tender platform** enables transparent management and monitoring of energy project tenders, including milestone validation and payment disbursements.
+
+This integration allows ECREEE e-Tender to securely retrieve **transaction and operational data** from **MicroPowerManager**, supporting:
+
+- Milestone verification
+- Performance-based disbursement
+- Financial transparency
+- Automated reporting
+
+---
+
+## Prerequisites
+
+Before starting, ensure the following:
+
+- Active **ECREEE e-Tender bidder account**
+- Access to a **MicroPowerManager instance** with transaction data
+- **Admin access** to MicroPowerManager to enable the integration plugin
+- Ability to generate API keys in MicroPowerManager
+
+---
+
+## Step 1: Access ECREEE e-Tender Platform
+
+1. Navigate to the ECREEE e-Tender login page
+2. Enter your registered email and password
+3. Click **Sign In** to access your dashboard
+
+![Ecreee Login Page](images/ecreee-e-tender-login-page.png)
+
+---
+
+## Step 2: Enable ECREEE e-Tender Plugin in MicroPowerManager
+
+Before ECREEE e-Tender can access your data, the integration plugin must be enabled in MicroPowerManager.
+
+1. Log in to your **MicroPowerManager** instance
+2. Navigate to **Settings** → **Configuration** → **Plugins**
+3. Locate the **ECREEE E-Tender** plugin
+4. Toggle the plugin **ON**
+
+---
+
+## Step 3: Generate API Key in MicroPowerManager
+
+To allow secure data access:
+
+1. In MicroPowerManager, go to **Settings** → **API Keys**
+2. Click **Generate New API Key**
+3. Copy and securely store the generated API key
+
+> This API key grants access to transaction and operational data.  
+> Do not share it publicly.
+
+---
+
+## Step 4: Register MicroPowerManager in ECREEE e-Tender (CRM Setup)
+
+1. In the ECREEE e-Tender dashboard, navigate to **CRM Management**
+2. Click **Create New CRM**
+3. Fill in the following fields:
+   - **CRM**: Select **`Micropower Manager`**
+   - **API Key**: Paste the API key generated in Step 3
+   - **Is Active**: Select **Yes**
+4. Click **Create** to save the configuration
+
+![Ecreee CRM Management Page](images/ecreee-e-tender-crm-management-page.png)
+
+---
+
+## Step 5: Verify Integration
+
+Once the CRM is created and active:
+
+1. ECREEE e-Tender will automatically begin retrieving data from MicroPowerManager
+2. Navigate to relevant tender or milestone views
+3. Confirm that transaction and progress data is visible
+
+Data synchronization occurs automatically based on ECREEE e-Tender schedules.
+
+---
+
+## How the Integration Works
+
+1. ECREEE e-Tender securely authenticates using the provided API key
+2. Embedded integration services query MicroPowerManager for:
+   - Payment transactions
+   - Customer and site references
+   - Meter and device identifiers
+   - Timestamps and amounts
+3. Retrieved data is used to:
+   - Validate milestone completion
+   - Support disbursement approvals
+   - Enhance reporting and auditability
+
+> ⚙️ API queries are optimized for performance and reliability.
+
+---
+
+## Troubleshooting
+
+### No Data Visible
+
+- Confirm the plugin is enabled in MicroPowerManager
+- Ensure the API key is correct and active
+- Verify that transaction data exists in MPM
+
+### Authentication Errors
+
+- Regenerate the API key in MicroPowerManager
+- Update the key in ECREEE e-Tender CRM configuration
+
+### Incomplete Data
+
+- Check that transactions fall within the expected reporting period
+- Confirm site or project mappings in MicroPowerManager
+
+---
+
+## Support
+
+For assistance:
+
+- **ECREEE e-Tender issues**: Contact the ECREEE platform administrator
+- **MicroPowerManager issues**: Review system logs or contact the MPM support team
+
+---
+
+This integration enables **secure, automated, and transparent data exchange** between MicroPowerManager and ECREEE e-Tender, supporting performance-based project financing and milestone-driven disbursements.

src/backend/app/Models/MpmPlugin.php

@@ -46,6 +46,7 @@ class MpmPlugin extends BaseModelCentral {
     public const PROSPECT = 24;
     public const PAYSTACK_PAYMENT_PROVIDER = 25;
     public const TEXTBEE_SMS_GATEWAY = 26;
+    public const ECREEE_E_TENDER = 27;
 
     protected $table = 'mpm_plugins';
 

src/backend/app/Services/ApiResolvers/Data/ApiResolverMap.php

@@ -8,6 +8,7 @@
 use App\Services\ApiResolvers\AndroidGatewayCallbackApiResolver;
 use App\Services\ApiResolvers\DataExportResolver;
 use App\Services\ApiResolvers\DownloadingReportsResolver;
+use App\Services\ApiResolvers\EcreeeMeterDataApiResolver;
 use App\Services\ApiResolvers\OdysseyPaymentApiResolver;
 use App\Services\ApiResolvers\PaystackApiResolver;
 use App\Services\ApiResolvers\SwiftaPaymentApiResolver;
@@ -28,6 +29,7 @@ class ApiResolverMap {
     public const AFRICAS_TALKING_API = 'api/africas-talking/callback';
     public const VODACOM_MOBILE_MONEY = 'api/vodacom/';
     public const PAYSTACK_API = 'api/paystack/';
+    public const ECREEE_METER_DATA_API = 'api/ecreee-e-tender/ecreee-meter-data';
 
     public const RESOLVABLE_APIS = [
         self::TEST_API,
@@ -41,6 +43,7 @@ class ApiResolverMap {
         self::VODACOM_MOBILE_MONEY,
         self::ODYSSEY_PAYMENTS_API,
         self::PAYSTACK_API,
+        self::ECREEE_METER_DATA_API,
     ];
 
     private const API_RESOLVER = [
@@ -55,6 +58,7 @@ class ApiResolverMap {
         self::VODACOM_MOBILE_MONEY => VodacomMobileMoneyApiResolver::class,
         self::ODYSSEY_PAYMENTS_API => OdysseyPaymentApiResolver::class,
         self::PAYSTACK_API => PaystackApiResolver::class,
+        self::ECREEE_METER_DATA_API => EcreeeMeterDataApiResolver::class,
     ];
 
     /**

src/backend/app/Services/ApiResolvers/EcreeeMeterDataApiResolver.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\ApiResolvers;
+
+use App\Auth\ApiKeyAuthenticatable;
+use App\Models\Company;
+use App\Models\User;
+use App\Services\Interfaces\IApiResolver;
+use Illuminate\Http\Request;
+use Illuminate\Validation\ValidationException;
+
+class EcreeeMeterDataApiResolver implements IApiResolver {
+    public function resolveCompanyId(Request $request): int {
+        // The user should already be authenticated by the 'api-key' guard
+        /** @var ApiKeyAuthenticatable|Company|User|null $user */
+        $user = auth('api-key')->user();
+
+        if ($user === null) {
+            throw ValidationException::withMessages(['authorization' => 'Company could not be resolved from authenticated API key']);
+        }
+
+        if ($user instanceof ApiKeyAuthenticatable) {
+            return $user->getCompany()->id;
+        }
+
+        return $user->id;
+    }
+}

src/backend/app/Services/TokenService.php

@@ -37,14 +37,23 @@ public function delete($model): ?bool {
         throw new \Exception('Method delete() not yet implemented.');
     }
 
-    /**
-     * @return Collection<int, Token>|LengthAwarePaginator<int, Token>
-     */
     public function getAll(?int $limit = null): Collection|LengthAwarePaginator {
         if ($limit) {
             return $this->token->newQuery()->paginate($limit);
         }
 
         return $this->token->newQuery()->get();
     }
+
+    /**
+     * @return Collection<int, Token>
+     */
+    public function getTokensInRange(?string $startDate, ?string $endDate): Collection {
+        return $this->token->newQuery()->with(['transaction.device'])
+            ->whereHas('transaction.device', function ($query) {
+                $query->where('device_type', 'meter');
+            })
+            ->whereBetween('created_at', [$startDate, $endDate])
+            ->get();
+    }
 }

src/backend/bootstrap/providers.php

@@ -13,6 +13,7 @@
 use Inensus\DalyBms\Providers\DalyBmsServiceProvider;
 use Inensus\DemoMeterManufacturer\Providers\DemoMeterManufacturerServiceProvider;
 use Inensus\DemoShsManufacturer\Providers\DemoShsManufacturerServiceProvider;
+use Inensus\EcreeeETender\Providers\EcreeeETenderServiceProvider;
 use Inensus\GomeLongMeter\Providers\GomeLongMeterServiceProvider;
 use Inensus\KelinMeter\Providers\KelinMeterServiceProvider;
 use Inensus\MesombPaymentProvider\Providers\MesombServiceProvider;
@@ -62,4 +63,5 @@
     DemoShsManufacturerServiceProvider::class,
     PaystackPaymentProviderServiceProvider::class,
     TextbeeSmsGatewayServiceProvider::class,
+    EcreeeETenderServiceProvider::class,
 ];

src/backend/composer.json

@@ -93,7 +93,8 @@
       "Inensus\\DemoShsManufacturer\\": "packages/inensus/demo-shs-manufacturer/src",
       "Inensus\\DemoMeterManufacturer\\": "packages/inensus/demo-meter-manufacturer/src",
       "Inensus\\PaystackPaymentProvider\\": "packages/inensus/paystack-payment-provider/src",
-      "Inensus\\TextbeeSmsGateway\\": "packages/inensus/textbee-sms-gateway/src"
+      "Inensus\\TextbeeSmsGateway\\": "packages/inensus/textbee-sms-gateway/src",
+      "Inensus\\EcreeeETender\\": "packages/inensus/ecreee-e-tender/src"
     }
   },
   "autoload-dev": {

src/backend/database/migrations/2025_12_08_230311_add_ecree_e_tender_plugin_to_mpm_plugins_table.php

@@ -0,0 +1,39 @@
+<?php
+
+use App\Models\MpmPlugin;
+use Carbon\Carbon;
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+
+return new class extends Migration {
+    /**
+     * Run the migrations.
+     *
+     * @return void
+     */
+    public function up() {
+        DB::table('mpm_plugins')->insert([
+            [
+                'id' => MpmPlugin::ECREEE_E_TENDER,
+                'name' => 'Ecreee E-Tender',
+                'description' => 'This plugin integrates Ecreee e-tender integration to Micropowermanager.',
+                'tail_tag' => null,
+                'installation_command' => 'ecreee-e-tender:install',
+                'root_class' => 'EcreeeETender',
+                'created_at' => Carbon::now(),
+                'updated_at' => Carbon::now(),
+            ],
+        ]);
+    }
+
+    /**
+     * Reverse the migrations.
+     *
+     * @return void
+     */
+    public function down() {
+        DB::table('mpm_plugins')
+            ->where('id', MpmPlugin::ECREEE_E_TENDER)
+            ->delete();
+    }
+};

src/backend/packages/inensus/ecreee-e-tender/README.md

@@ -0,0 +1,9 @@
+## Package-Development-Starter-Pack
+
+### Starter pack for package development to MicroPowerManager
+
+- This repo has created by the MicroPowerManager development team for developers who will develop a new package for MicroPowerManager.
+- The team suggests developers use this repo when they decide to develop new packages to MicroPowerManager.
+- Developers should clone our `Core` project with this url `https://github.com/inensus/MPManager` first. After cloning and running the core project, They have to go into laravel container & run `php artisan micropowermanager:new-package {{package-name}}` command to clone `this repo` into packages folder in MicroPowerManager core project.
+- After cloning Package-Development-Starter-Pack, developers can keep developing the package inside of core project.
+- When the developing will have been finished they can upload their packages to `https://packagist.org/` for the other developers usage

src/backend/packages/inensus/ecreee-e-tender/composer.json

@@ -0,0 +1,27 @@
+{
+  "name": "inensus/ecreee-e-tender",
+  "description": "Integration of Ecreee e-tender platform with MicroPowerManager Mini-Grid management system.",
+  "type": "package",
+  "require": {},
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "inensus",
+      "email": "developer@inensus.com",
+      "role": "Developer"
+    }
+  ],
+  "minimum-stability": "dev",
+  "autoload": {
+    "psr-4": {
+      "Inensus\\EcreeeETender\\": "src"
+    }
+  },
+  "extra": {
+    "laravel": {
+      "providers": [
+        "Inensus\\EcreeeETender\\Providers\\EcreeeETenderServiceProvider"
+      ]
+    }
+  }
+}

src/backend/packages/inensus/ecreee-e-tender/config/ecreee-e-tender.php

@@ -0,0 +1,4 @@
+<?php
+
+return [
+];

src/backend/packages/inensus/ecreee-e-tender/src/Console/Commands/InstallPackage.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Inensus\EcreeeETender\Console\Commands;
+
+use Illuminate\Console\Command;
+
+class InstallPackage extends Command {
+    protected $signature = 'ecreee-e-tender:install';
+    protected $description = 'Install Ecreee e-tender Package';
+
+    public function __construct(
+    ) {
+        parent::__construct();
+    }
+
+    public function handle(): void {
+        $this->info('Installing Ecreee e-tender Integration Package\n');
+        $this->info('Package installed successfully..');
+    }
+}