From 6af0d7ea735e814abb6525522d6a16daff626e2f Mon Sep 17 00:00:00 2001
From: Claude <developers@lethean.io>
Date: Sat, 4 Apr 2026 11:49:19 +0100
Subject: [PATCH] feat: API Resources for consistent JSON formatting

NameResource transforms alias data with parsed type, capabilities,
and owner_type (registry/community). ClaimResource formats claim
responses. Lookup endpoint uses NameResource, claim uses ClaimResource
with additional message. Follows CorePHP patterns/building-rest-apis.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 app/Mod/Names/Controllers/NamesController.php | 22 +++-----
 app/Mod/Names/Resources/ClaimResource.php     | 28 ++++++++++
 app/Mod/Names/Resources/NameResource.php      | 51 +++++++++++++++++++
 3 files changed, 87 insertions(+), 14 deletions(-)
 create mode 100644 app/Mod/Names/Resources/ClaimResource.php
 create mode 100644 app/Mod/Names/Resources/NameResource.php

diff --git a/app/Mod/Names/Controllers/NamesController.php b/app/Mod/Names/Controllers/NamesController.php
index e66f878..6ba5a2c 100644
--- a/app/Mod/Names/Controllers/NamesController.php
+++ b/app/Mod/Names/Controllers/NamesController.php
@@ -13,6 +13,7 @@ use Mod\Chain\Services\DaemonRpc;
 use Mod\Chain\Services\WalletRpc;
 use Mod\Names\Actions;
 use Mod\Names\Models\NameClaim;
+use Mod\Names\Resources;
 
 /**
  * .lthn TLD registrar API.
@@ -49,13 +50,9 @@ class NamesController extends Controller
             return response()->json(['error' => 'Name not registered'], 404);
         }
 
-        return response()->json([
-            'name' => $name,
-            'fqdn' => "{$name}.lthn",
-            'address' => $alias['address'] ?? '',
-            'comment' => $alias['comment'] ?? '',
-            'registered' => true,
-        ]);
+        $alias['name'] = $name;
+
+        return (new Resources\NameResource($alias))->response();
     }
 
     /**
@@ -529,13 +526,10 @@ class NamesController extends Controller
     {
         $claim = Actions\SubmitClaim::run($request->only(['name', 'email']));
 
-        return response()->json([
-            'claim_id' => $claim->claim_id,
-            'name' => $claim->name,
-            'fqdn' => "{$claim->name}.lthn",
-            'status' => $claim->status,
-            'message' => "Your claim has been submitted. We will notify you at {$claim->email} when approved.",
-        ], 201);
+        return (new Resources\ClaimResource($claim))
+            ->additional(['message' => "Your claim has been submitted. We will notify you at {$claim->email} when approved."])
+            ->response()
+            ->setStatusCode(201);
     }
 
     /**
diff --git a/app/Mod/Names/Resources/ClaimResource.php b/app/Mod/Names/Resources/ClaimResource.php
new file mode 100644
index 0000000..1b3cd83
--- /dev/null
+++ b/app/Mod/Names/Resources/ClaimResource.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mod\Names\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/**
+ * Consistent JSON format for claim responses.
+ *
+ *   return new ClaimResource($claim);
+ */
+class ClaimResource extends JsonResource
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'claim_id' => $this->claim_id,
+            'name' => $this->name,
+            'fqdn' => $this->name . '.lthn',
+            'email' => $this->email,
+            'status' => $this->status,
+            'created_at' => $this->created_at?->toIso8601String(),
+        ];
+    }
+}
diff --git a/app/Mod/Names/Resources/NameResource.php b/app/Mod/Names/Resources/NameResource.php
new file mode 100644
index 0000000..18bd4f6
--- /dev/null
+++ b/app/Mod/Names/Resources/NameResource.php
@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mod\Names\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/**
+ * Consistent JSON format for name lookups.
+ *
+ *   return new NameResource($aliasData);
+ */
+class NameResource extends JsonResource
+{
+    public function toArray(Request $request): array
+    {
+        $address = $this['address'] ?? '';
+        $comment = $this['comment'] ?? '';
+        $parsed = $this->parseComment($comment);
+
+        $registrarWallets = [
+            'iTHNHN11yXMeBphpFSuHnDaSJ15QxiSEJXNY59VKbxKq4ype4xAH1PZHd1EKTknkPK9hHTu2G2tBBZzvrcRFaYMF8vWTzFZjGY' => 'registry',
+            'iTHNUNiuu3VP1yy8xH2y5iQaABKXurdjqZmzFiBiyR4dKG3j6534e9jMriY6SM7PH8NibVwVWW1DWJfQEWnSjS8n3Wgx86pQpY' => 'testnet-registry',
+        ];
+
+        return [
+            'name' => $this['alias'] ?? $this['name'] ?? '',
+            'fqdn' => ($this['alias'] ?? $this['name'] ?? '') . '.lthn',
+            'address' => $address,
+            'owner_type' => isset($registrarWallets[$address]) ? 'registry' : 'community',
+            'type' => $parsed['type'] ?? 'user',
+            'capabilities' => ! empty($parsed['cap']) ? explode(',', $parsed['cap']) : [],
+            'comment' => $comment,
+        ];
+    }
+
+    private function parseComment(string $comment): array
+    {
+        $parsed = [];
+        foreach (explode(';', $comment) as $pair) {
+            $parts = explode('=', $pair, 2);
+            if (count($parts) === 2) {
+                $parsed[$parts[0]] = $parts[1];
+            }
+        }
+
+        return $parsed;
+    }
+}