Add SmartTwin event subscriber skeleton

.env.example

@@ -77,6 +77,18 @@ SENTRY_LARAVEL_DSN=
 # Econobis API settings
 ECONOBIS_ENABLED=false
 
+# SmartTwin API settings
+SMARTTWIN_ENABLED=false
+SMARTTWIN_BASE_URI=https://hoomdossier.test.smarttwin.nl
+SMARTTWIN_KEY=
+SMARTTWIN_DEBUG=false
+# Key SmartTwin uses in X-Webhook-ApiKey header when calling back our webhook
+SMARTTWIN_API_SIGN_KEY=
+# Previous sign key(s) for zero-downtime key rotation, comma-separated (optional)
+SMARTTWIN_PREVIOUS_API_SIGN_KEY=
+# Subscription ID returned by api:smarttwin:subscribe
+SMARTTWIN_SUBSCRIPTION_ID=
+
 # Mail adresses
 ADMIN_MAIL_ADDRESS='[email protected],[email protected]'
 HOOM_CONTACT_EMAIL_WHITELIST='[email protected],[email protected]'

app/Console/Commands/Api/SmartTwin/GetAdviceResults.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace App\Console\Commands\Api\SmartTwin;
+
+use App\Models\Building;
+use Illuminate\Console\Command;
+use App\Jobs\SmartTwin\Out\GetAdviceResults as GetAdviceResultsJob;
+
+class GetAdviceResults extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'api:smarttwin:get-advice-results
+                            {buildingId? : Only process this specific building ID}';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Fallback cron: get SmartTwin advice results not yet fetched by a job';
+
+    /**
+     * Execute the console command.
+     */
+    public function handle()
+    {
+        Building::containsPendingSmartTwinAdvices()
+            ->when($this->argument('buildingId'), fn($q, $id) => $q->where('id', $id))
+            ->chunk(5, function ($buildings) {
+            /** @var Building $building */
+                foreach ($buildings as $building) {
+                    $this->line("Fallback cron to get advice results for " . $building->getKey());
+
+                    foreach ($building->getSmartTwinCallbacks() as $callback) {
+                        GetAdviceResultsJob::dispatchSync($callback, $building->getKey());
+                    }
+                }
+            });
+    }
+}

app/Console/Commands/Api/SmartTwin/SubscribeCommand.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace App\Console\Commands\Api\SmartTwin;
+
+use App\Services\SmartTwin\Api\SmartTwinApi;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Log;
+
+class SubscribeCommand extends Command
+{
+    protected $signature = 'api:smarttwin:subscribe
+                            {--name= : Subscriber name (defaults to app name)}';
+
+    protected $description = 'Register an event subscription with the SmartTwin API. Outputs the subscriptionId to store in SMARTTWIN_SUBSCRIPTION_ID.';
+
+    public function handle(SmartTwinApi $api): int
+    {
+        $subscriberName = $this->option('name') ?? config('app.name');
+        $callbackUrl = route('api.v1.smarttwin.store');
+        $signKey = config('hoomdossier.services.smarttwin.sign-key', '') ?: null;
+
+        $this->info('Subscribing to SmartTwin events...');
+        $this->line("  Subscriber : {$subscriberName}");
+        $this->line("  Callback   : {$callbackUrl}");
+
+        $response = $api->events()->subscribe($subscriberName, $callbackUrl, $signKey);
+
+        $subscriptionId = $response['subscriptionId'] ?? $response['Value'] ?? null;
+
+        if (! $subscriptionId) {
+            $this->error('Subscription failed: no subscriptionId in response.');
+            return self::FAILURE;
+        }
+
+        Log::info('SmartTwin event subscription created', [
+            'subscriptionId' => $subscriptionId,
+            'subscriberName' => $subscriberName,
+            'callbackUrl'    => $callbackUrl,
+        ]);
+
+        $this->info('Subscribed successfully!');
+        $this->newLine();
+        $this->comment('Add the following to your .env file:');
+        $this->line("SMARTTWIN_SUBSCRIPTION_ID={$subscriptionId}");
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/Api/SmartTwin/UnsubscribeCommand.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Console\Commands\Api\SmartTwin;
+
+use App\Services\SmartTwin\Api\SmartTwinApi;
+use Illuminate\Console\Command;
+
+class UnsubscribeCommand extends Command
+{
+    protected $signature = 'api:smarttwin:unsubscribe
+                            {subscriptionId? : The subscription ID to cancel (defaults to SMARTTWIN_SUBSCRIPTION_ID)}';
+
+    protected $description = 'Cancel an event subscription with the SmartTwin API.';
+
+    public function handle(SmartTwinApi $api): int
+    {
+        $subscriptionId = $this->argument('subscriptionId')
+            ?? config('hoomdossier.services.smarttwin.subscription-id');
+
+        if (! $subscriptionId) {
+            $this->error('No subscriptionId provided. Pass it as argument or set SMARTTWIN_SUBSCRIPTION_ID in .env.');
+            return self::FAILURE;
+        }
+
+        $this->info("Unsubscribing from SmartTwin events (ID: {$subscriptionId})...");
+
+        $api->events()->unsubscribe($subscriptionId);
+
+        $this->info('Unsubscribed successfully.');
+
+        return self::SUCCESS;
+    }
+}

app/Enums/SmartTwin/EventType.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace App\Enums\SmartTwin;
+
+enum EventType: string
+{
+    case RESIDENT_SCAN_FINISHED = 'smarttwin.quickscan.finalized';
+    case COACH_SCAN_FINISHED    = 'smarttwin.advice.finalized';
+}

app/Events/AccountVerified.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Events;
+
+use App\Models\Account;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class AccountVerified
+{
+    use Dispatchable, SerializesModels;
+
+    public function __construct(public Account $account)
+    {
+    }
+}

app/Events/SmartTwinCallbackReceived.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Events;
+
+use App\Models\Building;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class SmartTwinCallbackReceived
+{
+    use Dispatchable, SerializesModels;
+
+    public Building $building;
+
+    /**
+     * The callback entries that were newly added to the building.
+     *
+     * @var array<int, mixed>
+     */
+    public array $addedCallbacks;
+
+    /**
+     * @param  array<int, mixed>  $addedCallbacks
+     */
+    public function __construct(Building $building, array $addedCallbacks)
+    {
+        $this->building       = $building;
+        $this->addedCallbacks = $addedCallbacks;
+    }
+}

app/Events/UserDeleted.php

@@ -11,12 +11,7 @@ class UserDeleted
 {
     use Dispatchable, InteractsWithSockets, SerializesModels;
 
-    /**
-     * Create a new job instance.
-     *
-     * @return void
-     */
-    public function __construct(public array $cooperation, public array $accountRelated)
+    public function __construct(public array $cooperation, public array $context)
     {
     }
 

app/Helpers/Hoomdossier.php

@@ -21,6 +21,11 @@ public static function hasEnabledEconobisCalls(): bool
         return config('hoomdossier.services.econobis.enabled', false);
     }
 
+    public static function hasEnabledSmartTwinCalls(): bool
+    {
+        return config('hoomdossier.services.smarttwin.enabled', false);
+    }
+
     /**
      * @deprecated
      * Return the most credible value from a given collection.

app/Helpers/Models/BuildingSettingHelper.php

@@ -11,6 +11,7 @@ class BuildingSettingHelper
     const SHORT_SMALL_MEASURES_ENABLED_LITE_SCAN = 'small_measures_enabled_lite-scan';
     const SHORT_SCAN_ENABLED_QUICK_SCAN = 'scan_enabled_quick-scan';
     const SHORT_SCAN_ENABLED_LITE_SCAN = 'scan_enabled_lite-scan';
+    const SHORT_SMARTTWIN_DOSSIER_ID = 'smarttwin_dossier_id';
 
     public static function getAvailableSettings(): array
     {

app/Http/Controllers/Api/V1/SmartTwinController.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Helpers\Models\BuildingSettingHelper;
+use App\Models\Building;
+use App\Models\BuildingSetting;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use Illuminate\Support\Facades\Log;
+
+class SmartTwinController
+{
+    public function store(Request $request): Response
+    {
+        $payload = $request->json()->all();
+
+        Log::debug('SmartTwin webhook received', $payload);
+
+        $data = $payload['data'] ?? null;
+
+        if (! is_array($data)) {
+            Log::warning('SmartTwin webhook missing data key', $payload);
+            return response()->noContent();
+        }
+
+        $dossierId = $data['DossierId'] ?? null;
+
+        if (! $dossierId) {
+            Log::warning('SmartTwin webhook missing DossierId', $data);
+            return response()->noContent();
+        }
+
+        $building = BuildingSetting::forShort(BuildingSettingHelper::SHORT_SMARTTWIN_DOSSIER_ID)
+            ->where('value', $dossierId)
+            ->first()
+            ?->building;
+
+        if (! $building instanceof Building) {
+            Log::warning('SmartTwin webhook: no building found for DossierId', ['dossierId' => $dossierId]);
+            return response()->noContent();
+        }
+
+        $callbacks = $building->getSmartTwinCallbacks();
+        $callbacks[] = $data;
+
+        $building->smarttwin_callback = $callbacks;
+        $building->save();
+
+        Log::debug('SmartTwin webhook stored callback for building', [
+            'building_id' => $building->getKey(),
+            'dossierId'   => $dossierId,
+        ]);
+
+        return response()->noContent();
+    }
+}

app/Http/Middleware/Api/SmartTwinSigned.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace App\Http\Middleware\Api;
+
+use Closure;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+class SmartTwinSigned
+{
+    public function handle(Request $request, Closure $next): Response
+    {
+        $header = $request->header('X-Webhook-ApiKey', '');
+        $signKey = config('hoomdossier.services.smarttwin.sign-key', '');
+        $previousSignKey = config('hoomdossier.services.smarttwin.previous-sign-key', '');
+
+        $previousKeys = $previousSignKey !== ''
+            ? array_map('trim', explode(',', $previousSignKey))
+            : [];
+
+        $validKeys = array_filter([$signKey, ...$previousKeys], fn($k) => $k !== '');
+
+        if ($header !== '' && in_array($header, $validKeys, true)) {
+            return $next($request);
+        }
+
+        return response()->json(['error' => 'Unauthorized'], 401);
+    }
+}

app/Jobs/SmartTwin/Out/CreateCoachAccount.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace App\Jobs\SmartTwin\Out;
+
+use App\Helpers\Hoomdossier;
+use App\Helpers\Queue;
+use App\Models\User;
+use App\Services\SmartTwin\Api\SmartTwinApi;
+use App\Services\SmartTwin\Api\UserRole;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+class CreateCoachAccount implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries = 3;
+
+    public function __construct(public User $user)
+    {
+        $this->queue = Queue::APP_EXTERNAL;
+    }
+
+    public function handle(SmartTwinApi $api): void
+    {
+        if (! Hoomdossier::hasEnabledSmartTwinCalls()) {
+            Log::debug('SmartTwin calls are disabled, skipping CreateCoachAccount for user ' . $this->user->id);
+            return;
+        }
+
+        if (! empty($this->user->extra['smarttwin_user_id'] ?? null)) {
+            return;
+        }
+
+        $response = $api->user()->create(
+            $this->user->account->email,
+            $this->user->first_name ?? '',
+            $this->user->last_name ?? '',
+            UserRole::Advisor,
+        );
+
+        $userId = $response['userId'] ?? null;
+        if (! empty($userId)) {
+            $extra = $this->user->extra ?? [];
+            $extra['smarttwin_user_id'] = $userId;
+            $this->user->extra = $extra;
+            $this->user->save();
+        }
+    }
+}