Route SMS voice uploads through Transfer with wallet billing.

Add a service API for the Ladill SMS platform to store voice recordings in Transfer and charge monthly storage from the customer wallet.

Co-authored-by: Cursor <cursoragent@cursor.com>

.env.example

@@ -48,6 +48,9 @@ TRANSFER_MAIL_RETENTION_DAYS=30
 
 # Ladill Mail — large attachment uploads (service-to-service).
 TRANSFER_API_KEY_WEBMAIL=
+# Ladill SMS — voice message uploads (must match SMS_TRANSFER_API_KEY on platform).
+TRANSFER_API_KEY_SMS=
+TRANSFER_SMS_VOICE_MAX_UPLOAD_KB=5120
 
 AFIA_ENABLED=true
 AFIA_PRODUCT=transfer

app/Http/Controllers/Api/SmsVoiceTransferController.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Services\Identity\PublicIdUserResolver;
+use App\Services\Transfer\TransferService;
+use App\Support\DirectTransferFileUrl;
+use App\Support\TransferWalletErrors;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Str;
+use RuntimeException;
+
+/** Voice SMS audio uploads from the Ladill SMS platform (storage billed via Transfer). */
+class SmsVoiceTransferController extends Controller
+{
+    public function __construct(
+        private PublicIdUserResolver $users,
+        private TransferService $transfers,
+    ) {}
+
+    public function store(Request $request): JsonResponse
+    {
+        if ($request->attributes->get('service_caller') !== 'sms') {
+            return response()->json(['message' => 'Forbidden.'], 403);
+        }
+
+        $maxKb = max(256, (int) config('transfer.sms_voice_max_upload_kb', 5120));
+
+        $data = $request->validate([
+            'user' => ['required', 'string', 'max:64'],
+            'title' => ['nullable', 'string', 'max:120'],
+            'voice' => ['required', 'file', 'mimes:mp3,wav', 'max:'.$maxKb],
+        ]);
+
+        try {
+            $user = $this->users->resolve((string) $data['user']);
+        } catch (RuntimeException $e) {
+            return response()->json(['message' => $e->getMessage()], 422);
+        }
+
+        $voice = $request->file('voice');
+        $filename = $voice?->getClientOriginalName() ?: 'voice.mp3';
+        $title = trim((string) ($data['title'] ?? ''));
+        if ($title === '') {
+            $title = Str::limit('SMS voice: '.$filename, 120, '');
+        }
+
+        try {
+            $transfer = $this->transfers->create($user, [
+                'title' => $title,
+            ], [$voice]);
+        } catch (RuntimeException $e) {
+            $payload = ['message' => $e->getMessage()];
+            if (TransferWalletErrors::isInsufficientBalance($e)) {
+                $payload['error_code'] = TransferWalletErrors::CODE_INSUFFICIENT_WALLET;
+            }
+
+            return response()->json($payload, 422);
+        }
+
+        $transfer->load(['files', 'qrCode']);
+        $file = $transfer->files->first();
+        if ($file === null) {
+            return response()->json(['message' => 'Voice upload failed.'], 422);
+        }
+
+        return response()->json([
+            'data' => [
+                'direct_file_url' => DirectTransferFileUrl::for($transfer, $file),
+                'public_url' => $transfer->qrCode?->publicUrl(),
+                'transfer_id' => $transfer->id,
+                'file_id' => $file->id,
+                'paid_until' => $transfer->paid_until?->toIso8601String(),
+                'storage_gb' => $transfer->storageGb(),
+                'monthly_cost_ghs' => $transfer->monthlyCostGhs(),
+            ],
+        ], 201);
+    }
+}

app/Services/Identity/PublicIdUserResolver.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace App\Services\Identity;
+
+use App\Models\User;
+use Illuminate\Support\Facades\Http;
+use RuntimeException;
+
+/** Resolves a Ladill Transfer user mirror from a platform account public_id. */
+class PublicIdUserResolver
+{
+    public function resolve(string $publicId): User
+    {
+        $publicId = trim($publicId);
+        if ($publicId === '') {
+            throw new RuntimeException('User public_id is required.');
+        }
+
+        $existing = User::query()->where('public_id', $publicId)->first();
+        if ($existing) {
+            return $existing;
+        }
+
+        $base = rtrim((string) config('identity.api_url'), '/');
+        $key = (string) config('identity.api_key');
+        if ($base === '' || $key === '') {
+            throw new RuntimeException('Identity API is not configured.');
+        }
+
+        $res = Http::withToken($key)
+            ->acceptJson()
+            ->timeout(10)
+            ->get("{$base}/identity/profile", ['user' => $publicId]);
+
+        if ($res->failed()) {
+            throw new RuntimeException('Could not resolve the Ladill account.');
+        }
+
+        $data = $res->json('data');
+        if (! is_array($data)) {
+            throw new RuntimeException('Could not resolve the Ladill account.');
+        }
+
+        $email = trim((string) ($data['email'] ?? ''));
+        if ($email === '') {
+            $email = 'sms+'.$publicId.'@accounts.ladill.local';
+        }
+
+        return User::updateOrCreate(
+            ['public_id' => $publicId],
+            [
+                'name' => trim((string) ($data['name'] ?? '')) ?: 'Ladill user',
+                'email' => $email,
+            ],
+        );
+    }
+}

app/Support/DirectTransferFileUrl.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Support;
+
+use App\Models\QrCode;
+use App\Models\Transfer;
+use App\Models\TransferFile;
+use RuntimeException;
+
+class DirectTransferFileUrl
+{
+    public static function for(Transfer $transfer, TransferFile $file): string
+    {
+        $shortCode = $transfer->qrCode?->short_code;
+        if ($shortCode === null || $shortCode === '') {
+            throw new RuntimeException('Transfer file URL is unavailable.');
+        }
+
+        return QrCode::publicBaseUrl().'/q/'.$shortCode.'/transfer/files/'.$file->id;
+    }
+}

config/transfer.php

@@ -6,6 +6,7 @@ return [
     */
     'service_api_keys' => array_filter([
         'webmail' => env('TRANSFER_API_KEY_WEBMAIL'),
+        'sms' => env('TRANSFER_API_KEY_SMS'),
     ]),
 
     // GHS per GB per month of retention (see qr-suite-decomposition.md §7.3).
@@ -35,4 +36,7 @@ return [
     // Legacy env keys (billing is monthly until cancelled by non-payment + grace).
     'default_retention_days' => (int) env('TRANSFER_DEFAULT_RETENTION_DAYS', 30),
     'mail_retention_days' => (int) env('TRANSFER_MAIL_RETENTION_DAYS', 30),
+
+    // Voice SMS uploads from sms.ladill.com (via platform API).
+    'sms_voice_max_upload_kb' => (int) env('TRANSFER_SMS_VOICE_MAX_UPLOAD_KB', 5120),
 ];

deploy/shared.env.example

@@ -58,6 +58,9 @@ TRANSFER_MAIL_RETENTION_DAYS=30
 
 # Ladill Mail — large attachment uploads (must match WEBMAIL_TRANSFER_API_KEY).
 TRANSFER_API_KEY_WEBMAIL=
+# Ladill SMS — voice message uploads (must match SMS_TRANSFER_API_KEY on platform).
+TRANSFER_API_KEY_SMS=
+TRANSFER_SMS_VOICE_MAX_UPLOAD_KB=5120
 
 AFIA_ENABLED=true
 AFIA_PRODUCT=transfer

routes/api.php

@@ -3,11 +3,13 @@
 use App\Http\Controllers\Api\ChunkedUploadController;
 use App\Http\Controllers\Api\MeController;
 use App\Http\Controllers\Api\QrCodeController;
+use App\Http\Controllers\Api\SmsVoiceTransferController;
 use App\Http\Controllers\Api\TransferController;
 use Illuminate\Support\Facades\Route;
 
 Route::middleware('auth.service:transfer')->prefix('v1')->group(function () {
     Route::post('/transfers', [TransferController::class, 'store']);
+    Route::post('/transfers/voice', [SmsVoiceTransferController::class, 'store']);
     Route::get('/transfers/files', [\App\Http\Controllers\Api\TransferFilesController::class, 'index']);
     Route::post('/transfers/upload/init', [ChunkedUploadController::class, 'init']);
     Route::post('/transfers/upload/chunk', [ChunkedUploadController::class, 'chunk']);

tests/Feature/SmsVoiceTransferTest.php

@@ -0,0 +1,110 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Models\User;
+use App\Services\Transfer\TransferBillingService;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Http\UploadedFile;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Storage;
+use Illuminate\Support\Str;
+use Tests\Concerns\FakesTransferBilling;
+use Tests\TestCase;
+
+class SmsVoiceTransferTest extends TestCase
+{
+    use FakesTransferBilling;
+    use RefreshDatabase;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        Storage::fake('qr');
+        $this->fakeTransferBillingApi();
+        config([
+            'transfer.service_api_keys' => ['sms' => 'test-sms-key'],
+            'identity.api_url' => 'https://ladill.com/api',
+            'identity.api_key' => 'test-identity-key',
+        ]);
+    }
+
+    public function test_sms_service_can_upload_voice_recording(): void
+    {
+        $publicId = (string) Str::uuid();
+
+        Http::fake([
+            rtrim((string) config('identity.api_url'), '/').'/identity/profile*' => Http::response([
+                'data' => [
+                    'public_id' => $publicId,
+                    'name' => 'SMS User',
+                    'email' => 'sms@acme.com',
+                    'picture' => null,
+                ],
+            ]),
+        ]);
+
+        $voice = UploadedFile::fake()->create('greeting.mp3', 120, 'audio/mpeg');
+
+        $this->withToken('test-sms-key')
+            ->post('/api/v1/transfers/voice', [
+                'user' => $publicId,
+                'title' => 'SMS voice: greeting.mp3',
+                'voice' => $voice,
+            ])
+            ->assertCreated()
+            ->assertJsonPath('data.direct_file_url', fn (string $url) => str_contains($url, '/transfer/files/'))
+            ->assertJsonStructure([
+                'data' => [
+                    'direct_file_url',
+                    'public_url',
+                    'transfer_id',
+                    'file_id',
+                    'paid_until',
+                    'storage_gb',
+                    'monthly_cost_ghs',
+                ],
+            ]);
+
+        $this->assertDatabaseHas('users', ['public_id' => $publicId]);
+        $this->assertDatabaseCount('transfers', 1);
+    }
+
+    public function test_voice_upload_rejects_non_sms_callers(): void
+    {
+        config(['transfer.service_api_keys' => ['webmail' => 'test-webmail-key']]);
+
+        $this->withToken('test-webmail-key')
+            ->post('/api/v1/transfers/voice', [
+                'user' => (string) Str::uuid(),
+                'voice' => UploadedFile::fake()->create('greeting.mp3', 120, 'audio/mpeg'),
+            ])
+            ->assertForbidden();
+    }
+
+    public function test_voice_upload_returns_insufficient_wallet_error_code(): void
+    {
+        $publicId = (string) Str::uuid();
+        User::factory()->create(['public_id' => $publicId]);
+
+        $this->mock(TransferBillingService::class, function ($mock): void {
+            $mock->shouldReceive('chargeInitialPeriod')
+                ->once()
+                ->andThrow(new \RuntimeException(
+                    'Insufficient wallet balance for the first month of storage. Top up your Ladill wallet and try again.'
+                ));
+        });
+
+        $voice = UploadedFile::fake()->create('greeting.mp3', 120, 'audio/mpeg');
+
+        $this->withToken('test-sms-key')
+            ->post('/api/v1/transfers/voice', [
+                'user' => $publicId,
+                'voice' => $voice,
+            ])
+            ->assertStatus(422)
+            ->assertJsonPath('error_code', 'insufficient_wallet');
+
+        $this->assertDatabaseCount('transfers', 0);
+    }
+}