Add Vodacom Mobile Money integration package

Author: beesaferoot

docs/development/plugins.md

@@ -28,3 +28,313 @@ php artisan micropowermanager:new-package {package-name}
 
 This command creates a plugin template in the src/backend/packages/inensus folder. Upon creation, you can proceed with plugin development. You can check other plugins for reference.
 Additionally, this command will create UI folders for the newly created plugin. Move the created UI folder to the src/frontend/src/plugins folder.
+
+## Plugin Integration Process
+
+### Backend Integration
+
+To make your plugin discoverable and properly integrated with MPM, follow these steps:
+
+#### 1. Register Your Plugin's Installation Command
+
+Add your plugin's installation command class to the core application's console kernel:
+
+```php
+// src/backend/app/Console/Kernel.php
+
+use Inensus\YourPlugin\Console\Commands\InstallYourPluginPackage;
+
+class Kernel extends ConsoleKernel {
+    /**
+     * The Artisan commands provided by your application.
+     *
+     * @var array
+     */
+    protected $commands = [
+        Commands\AddMeterAddress::class,
+        InstallYourPluginPackage::class,
+        // ...other commands
+    ];
+    // ...
+}
+```
+
+#### 2. Register Your Plugin's Service Provider
+
+Add your plugin's service provider to the core application's configuration:
+
+```php
+// src/backend/config/app.php
+
+<?php
+
+return [
+    // rest of app configuration
+    // ...
+    /*
+    * Laravel Framework Service Providers...
+    */
+    'providers' => [
+        // ...other providers
+        Inensus\YourPlugin\Providers\YourPluginServiceProvider::class,
+    ]
+];
+```
+
+#### 3. Register Custom HTTP Route Resolver
+
+If your plugin requires API endpoints, register your custom route resolver:
+
+```php
+// src/backend/app/modules/Sharding/ApiResolvers/Data/ApiResolvers
+
+class ApiResolverMap {
+    // ...other API constants
+    public const YOUR_PLUGIN_API = 'api/your-plugin/callback';
+
+    public const RESOLVABLE_APIS = [
+        // ...other resolvable APIs
+        self::YOUR_PLUGIN_API,
+    ];
+
+    private const API_RESOLVER = [
+        // ...other API resolvers
+        self::YOUR_PLUGIN_API => YourPluginApiResolver::class,
+    ];
+
+    public function getResolvableApis(): array {
+        return self::RESOLVABLE_APIS;
+    }
+
+    public function getApiResolver(string $api): string {
+        return self::API_RESOLVER[$api];
+    }
+}
+```
+
+#### 4. Register Plugin in MPM Plugins Model
+
+Add your plugin to the MPM plugins model:
+
+```php
+// src/backend/app/Models/MpmPlugin.php
+
+<?php
+
+namespace App\Models;
+
+use App\Models\Base\BaseModelCore;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+
+class MpmPlugin extends BaseModelCore {
+    use HasFactory;
+    // ...other plugin constants
+    public const YOUR_PLUGIN = 19; // Add your plugin ID (increment sequentially)
+
+    protected $table = 'mpm_plugins';
+
+    public function plugins() {
+        return $this->hasMany(Plugins::class);
+    }
+}
+```
+
+#### 5. Create Required Migrations
+
+##### a. Protected Page Migration
+
+Create a migration to register your plugin's overview page:
+
+```php
+<?php
+
+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('protected_pages')->insert([
+            [
+                'name' => '/your-plugin/your-plugin-overview',
+                'created_at' => Carbon::now(),
+                'updated_at' => Carbon::now(),
+            ],
+        ]);
+    }
+
+    /**
+     * Reverse the migrations.
+     *
+     * @return void
+     */
+    public function down() {
+        DB::table('protected_pages')->where('name', '/your-plugin/your-plugin-overview')->delete();
+    }
+};
+```
+
+##### b. Plugin Models Migration
+
+Create tenant migrations for your plugin's models using:
+
+```bash
+php artisan make:migration-tenant
+```
+
+Make sure to create stub files for these migrations in your plugin's `database/migrations/` directory.
+
+##### c. Register Plugin in MPM Plugins Table
+
+Create a migration to add your plugin to the `mpm_plugins` table:
+
+```php
+<?php
+
+use App\Models\MpmPlugin;
+use Carbon\Carbon;
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+
+return new class extends Migration {
+    public function up() {
+        DB::table('mpm_plugins')->insert([
+            [
+                'id' => MpmPlugin::YOUR_PLUGIN,
+                'name' => 'YourPlugin',
+                'description' => 'This plugin developed for [describe your plugin functionality].',
+                'tail_tag' => 'Your Plugin',
+                'installation_command' => 'your-plugin:install',
+                'root_class' => 'YourPlugin',
+                'created_at' => Carbon::now(),
+                'updated_at' => Carbon::now(),
+            ],
+        ]);
+    }
+
+    public function down() {
+        DB::table('mpm_plugins')
+            ->where('id', MpmPlugin::YOUR_PLUGIN)
+            ->delete();
+    }
+};
+```
+
+#### 6. Implement Installation Command
+
+Create an installation command for your plugin:
+
+```php
+<?php
+
+namespace Inensus\YourPlugin\Console\Commands;
+
+use Illuminate\Console\Command;
+use Inensus\YourPlugin\Services\YourPluginService;
+
+class InstallPackage extends Command {
+    protected $signature = 'your-plugin:install';
+    protected $description = 'Install YourPlugin Package';
+
+    public function __construct(
+        private YourPluginService $pluginService,
+    ) {
+        parent::__construct();
+    }
+
+    public function handle(): void {
+        $this->info('Installing YourPlugin Integration Package\n');
+        $this->pluginService->initialize();
+        $this->info('Package installed successfully..');
+    }
+}
+```
+
+#### 7. Register Plugin in Composer.json
+
+Add your plugin to the `autoload-dev` section in composer.json:
+
+```json
+"autoload-dev": {
+  "psr-4": {
+    "Inensus\\YourPlugin\\": "packages/inensus/your-plugin/src",
+  }
+}
+```
+
+### Frontend Integration
+
+#### 1. Register Plugin Routes
+
+Add your plugin's routes to the exported routes:
+
+```js
+// src/frontend/src/ExportedRoutes.js
+
+import YourPluginOverview from "./plugins/your-plugin/js/modules/Overview/Overview"
+
+export const exportedRoutes = [
+  // ...other routes
+  {
+    path: "/your-plugin",
+    component: ChildRouteWrapper,
+    meta: {
+      sidebar: {
+        enabled_by_mpm_plugin_id: 19, // Your plugin ID from MpmPlugin
+        name: "Your Plugin",
+        icon: "plugin-icon", // Choose an appropriate icon
+      },
+    },
+    children: [
+      {
+        path: "your-plugin-overview",
+        component: YourPluginOverview,
+        meta: {
+          layout: "default",
+          sidebar: {
+            enabled: true,
+            name: "Overview",
+          },
+        },
+      },
+      // Add more routes as needed
+    ],
+  },
+]
+```
+
+#### 2. Mount Plugin Components
+
+Register your Vue components in the main app:
+
+```js
+// src/frontend/src/main.js
+
+import YourPlugin from "@/plugins/your-plugin/js/modules/Overview/Component"
+
+Vue.component("Your-Plugin", YourPlugin)
+
+// ...
+
+/*eslint-disable */
+const app = new Vue({
+  el: "#app",
+  // ...
+})
+```
+
+## Plugin Development Best Practices
+
+1. Keep your plugin self-contained as much as possible
+2. Follow the established directory structure for consistency
+3. Use the MPM core services when appropriate to maintain integration
+4. Thoroughly test your plugin's functionality before integration
+5. Document your plugin's features and configuration requirements
+6. Use proper versioning for your plugin package
+
+Remember to check existing plugins for reference implementations that might help guide your development.

src/backend/app/Console/Kernel.php

@@ -21,6 +21,7 @@
 use Inensus\SunKingSHS\Console\Commands\InstallPackage as InstallSunKingSHSPackage;
 use Inensus\SwiftaPaymentProvider\Console\Commands\InstallPackage as InstallSwiftaPaymentProviderPackage;
 use Inensus\ViberMessaging\Console\Commands\InstallPackage as InstallViberMessagingPackage;
+use Inensus\VodacomMobileMoney\Console\Commands\InstallPackage as InstallVodacomMobileMoneyPackage;
 use Inensus\WavecomPaymentProvider\Console\Commands\InstallPackage as InstallWaveComPackage;
 use Inensus\WaveMoneyPaymentProvider\Console\Commands\InstallPackage as InstallWaveMoneyPaymentProviderPackage;
 
@@ -50,6 +51,7 @@ class Kernel extends ConsoleKernel {
         InstallAngazaSHSPackage::class,
         InstallDalyBmsPackage::class,
         InstallAfricasTalkingPackage::class,
+        InstallVodacomMobileMoneyPackage::class,
     ];
 
     /**

src/backend/app/Models/MpmPlugin.php

@@ -30,6 +30,7 @@ class MpmPlugin extends BaseModelCore {
     public const DALY_BMS = 16;
     public const AGAZA_SHS = 17;
     public const AFRICAS_TALKING = 18;
+    public const VODACOM_MOBILE_MONEY = 19;
 
     protected $table = 'mpm_plugins';
 

src/backend/app/modules/Sharding/ApiResolvers/Data/ApiResolverMap.php

@@ -11,6 +11,7 @@
 use MPM\Sharding\ApiResolvers\SwiftaPaymentApiResolver;
 use MPM\Sharding\ApiResolvers\TestApiResolver;
 use MPM\Sharding\ApiResolvers\ViberMessagingApiResolver;
+use MPM\Sharding\ApiResolvers\VodacomMobileMoneyApiResolver;
 use MPM\Sharding\ApiResolvers\WaveMoneyApiResolver;
 
 class ApiResolverMap {
@@ -22,6 +23,7 @@ class ApiResolverMap {
     public const REPORT_DOWNLOADING_API = 'api/report-downloading';
     public const DATA_EXPORTING_API = 'api/export';
     public const AFRICAS_TALKING_API = 'api/africas-talking/callback';
+    public const VODACOM_MOBILE_MONEY = 'api/vodacom/';
 
     public const RESOLVABLE_APIS = [
         self::TEST_API,
@@ -32,6 +34,7 @@ class ApiResolverMap {
         self::REPORT_DOWNLOADING_API,
         self::DATA_EXPORTING_API,
         self::AFRICAS_TALKING_API,
+        self::VODACOM_MOBILE_MONEY,
     ];
 
     private const API_RESOLVER = [
@@ -43,6 +46,7 @@ class ApiResolverMap {
         self::REPORT_DOWNLOADING_API => DownloadingReportsResolver::class,
         self::DATA_EXPORTING_API => DataExportResolver::class,
         self::AFRICAS_TALKING_API => AfricasTalkingApiResolver::class,
+        self::VODACOM_MOBILE_MONEY => VodacomMobileMoneyApiResolver::class,
     ];
 
     public function getResolvableApis(): array {

src/backend/app/modules/Sharding/ApiResolvers/VodacomMobileMoneyApiResolver.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MPM\Sharding\ApiResolvers;
+
+use App\Exceptions\ValidationException;
+use Illuminate\Http\Request;
+
+class VodacomMobileMoneyApiResolver implements ApiResolverInterface {
+    public function resolveCompanyId(Request $request): int {
+        $segments = $request->segments();
+        if (count($segments) !== 5) {
+            throw new ValidationException('failed to parse company identifier from the webhook');
+        }
+
+        $companyId = $segments[3];
+
+        return (int) $companyId;
+    }
+}

src/backend/composer.json

@@ -84,6 +84,7 @@
       "Inensus\\DalyBms\\": "packages/inensus/daly-bms/src",
       "Inensus\\AngazaSHS\\": "packages/inensus/angaza-shs/src",
       "Inensus\\AfricasTalking\\": "packages/inensus/africas-talking/src",
+      "Inensus\\VodacomMobileMoney\\": "packages/inensus/vodacom-mobile-money/src",
       "Tests\\": "tests/"
     }
   },