[stable33] feat: add direct gateway integration service

lib/Service/GatewayDirectIntegrationService.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\TwoFactorGateway\Service;
+
+use OCA\TwoFactorGateway\Exception\MessageTransmissionException;
+
+/**
+ * Stable direct-integration path for other apps that only know the gateway id
+ * and destination identifier, and do not need user routing or instance
+ * selection details.
+ */
+class GatewayDirectIntegrationService {
+	public function __construct(
+		private GatewayRuntimeAvailabilityService $gatewayRuntimeAvailabilityService,
+	) {
+	}
+
+	public function ensureAvailable(string $gatewayId): void {
+		$this->gatewayRuntimeAvailabilityService->getGateway($gatewayId);
+	}
+
+	public function isGatewayComplete(string $gatewayId): bool {
+		return $this->gatewayRuntimeAvailabilityService->hasDirectGatewayFallback($gatewayId);
+	}
+
+	/**
+	 * @param array<string, mixed> $extra
+	 * @throws MessageTransmissionException
+	 */
+	public function send(string $gatewayId, string $identifier, string $message, array $extra = []): void {
+		$this->gatewayRuntimeAvailabilityService->getGateway($gatewayId)->send($identifier, $message, $extra);
+	}
+}

tests/php/Unit/Service/GatewayDirectIntegrationServiceTest.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\TwoFactorGateway\Tests\Unit\Service;
+
+use OCA\TwoFactorGateway\Provider\Gateway\IGateway;
+use OCA\TwoFactorGateway\Service\GatewayDirectIntegrationService;
+use OCA\TwoFactorGateway\Service\GatewayRuntimeAvailabilityService;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+class GatewayDirectIntegrationServiceTest extends TestCase {
+	private GatewayRuntimeAvailabilityService&MockObject $gatewayRuntimeAvailabilityService;
+	private GatewayDirectIntegrationService $service;
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->gatewayRuntimeAvailabilityService = $this->createMock(GatewayRuntimeAvailabilityService::class);
+		$this->service = new GatewayDirectIntegrationService($this->gatewayRuntimeAvailabilityService);
+	}
+
+	public function testEnsureAvailableDelegatesToRuntimeAvailabilityService(): void {
+		$gateway = $this->createMock(IGateway::class);
+
+		$this->gatewayRuntimeAvailabilityService->expects($this->once())
+			->method('getGateway')
+			->with('sms')
+			->willReturn($gateway);
+
+		$this->service->ensureAvailable('sms');
+	}
+
+	public function testIsGatewayCompleteDelegatesToRuntimeAvailabilityService(): void {
+		$this->gatewayRuntimeAvailabilityService->expects($this->once())
+			->method('hasDirectGatewayFallback')
+			->with('signal')
+			->willReturn(true);
+
+		$this->assertTrue($this->service->isGatewayComplete('signal'));
+	}
+
+	public function testSendDelegatesToResolvedGateway(): void {
+		$gateway = $this->createMock(IGateway::class);
+		$gateway->expects($this->once())
+			->method('send')
+			->with('+5511999999999', 'hello', []);
+
+		$this->gatewayRuntimeAvailabilityService->expects($this->once())
+			->method('getGateway')
+			->with('whatsapp')
+			->willReturn($gateway);
+
+		$this->service->send('whatsapp', '+5511999999999', 'hello');
+	}
+}