feat(domain): Add dedicated transfer API and verification metadata

Author: seebeen

README.md

@@ -6,6 +6,7 @@
 [![Packagist Version](https://img.shields.io/packagist/v/rnids/rsreg-epp-client?label=Release&style=flat-square)](https://packagist.org/packages/rnids/rsreg-epp-client)
 ![Packagist PHP Version](https://img.shields.io/packagist/dependency-v/rnids/rsreg-epp-client/php?label=PHP&logo=php&logoColor=white&logoSize=auto&style=flat-square)
 ![Static Badge](https://img.shields.io/badge/RNIDS-RSreg-3858e9?style=flat-square)
+[![codecov](https://codecov.io/github/oblakhost/rnids-rsreg-client-php/graph/badge.svg?token=0UMFP9CL35)](https://codecov.io/github/oblakhost/rnids-rsreg-client-php)
 [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/oblakhost/rnids-rsreg-client-php/release.yml?label=Build&event=push&style=flat-square&logo=githubactions&logoColor=white&logoSize=auto)](https://github.com/oblakhost/rnids-rsreg-client-php/actions/workflows/release.yml)
 
 </div>
@@ -56,7 +57,7 @@ $client->close();
 Common fluent entry points:
 
 - Session: `$client->session()->hello()`, `login()`, `logout()`, `poll()`
-- Domain: `$client->domain()->check()`, `info()`, `register()`, `renew()`, `update()`, `delete()`, `transfer()`
+- Domain: `$client->domain()->check()`, `info()`, `register()`, `renew()`, `update()`, `delete()`, `transfer()`, `getCode()`, `getState()`
 - Contact: `$client->contact()->check()`, `create()`, `info()`, `update()`, `delete()`
 - Host: `$client->host()->check()`, `info()`, `create()`, `update()`, `delete()`
 

bin/rsreg

@@ -3,7 +3,12 @@
 
 declare(strict_types=1);
 
-require_once __DIR__ . '/../vendor/autoload.php';
+foreach ([__DIR__ . '/../../../autoload.php', __DIR__ . '/../vendor/autoload.php'] as $file) {
+    if (file_exists($file)) {
+        require $file;
+        break;
+    }
+}
 
 /**
  * @return never

composer.lock

@@ -32,6 +32,9 @@ Policy behavior:
 
 - `id` is optional. If omitted/empty, library auto-generates a contact ID.
 - Contact IDs are normalized to the `OBL-` prefix before sending create commands.
+- `postalInfo.name` is required by default.
+  - Exception: it may be empty when `extension.isLegalEntity = '1'`
+    and `postalInfo.organization` is provided.
 - `extension.identDescription` is enforced to:
   `Object Creation provided by Oblak Solutions.`
 

docs/api-contact.md

@@ -158,21 +158,17 @@ At least one mutation key must be present: `add`, `remove`, `registrant`, or `au
 
 Deletes a domain.
 
-### `transfer(array $request): array`
+### `transfer(string $domain, string $transferCode): array`
 
-Handles transfer lifecycle operations (`request|query|cancel|approve|reject`).
+Approves a domain transfer using the provided transfer code.
 
-Request shape:
+### `getCode(string $domain): array`
 
-```php
-array{
-  operation?: mixed,
-  name?: mixed,
-  period?: mixed,
-  periodUnit?: mixed,
-  authInfo?: mixed
-}
-```
+Runs transfer operation `request` for the domain.
+
+### `getState(string $domain): array`
+
+Runs transfer operation `query` for the domain.
 
 Response shape:
 

docs/api-domain.md

@@ -47,9 +47,11 @@ public function checkFromArray(array $request): ContactCheckRequest
      */
     public function createFromArray(array $request): ContactCreateRequest
     {
+        $extension = $this->optionalExtension($request, true);
+
         return new ContactCreateRequest(
             $this->contactIdPolicy->normalizeForCreate($request['id'] ?? null),
-            $this->requirePostalInfo($request),
+            $this->requirePostalInfoForCreate($request, $extension),
             $this->optionalNullableString($request, 'voice'),
             $this->optionalNullableString($request, 'fax'),
             $this->requireString(
@@ -59,7 +61,7 @@ public function createFromArray(array $request): ContactCreateRequest
             ),
             $this->optionalNullableString($request, 'authInfo'),
             $this->optionalDisclose($request),
-            $this->optionalExtension($request, true),
+            $extension,
         );
     }
 
@@ -152,6 +154,24 @@ private function requirePostalInfo(array $request): ContactPostalInfo
         return $this->parsePostalInfo($postalInfo);
     }
 
+    /**
+     * @param array<string, mixed> $request
+     */
+    private function requirePostalInfoForCreate(array $request, ?ContactExtension $extension): ContactPostalInfo
+    {
+        $postalInfo = $this->requirePostalInfo($request);
+
+        if ('' !== \trim($postalInfo->name)) {
+            return $postalInfo;
+        }
+
+        if ($this->isLegalEntityCreateWithoutNaturalPersonName($extension, $postalInfo)) {
+            return $postalInfo;
+        }
+
+        throw new \InvalidArgumentException('Contact postalInfo key "name" must be a non-empty string.');
+    }
+
     /**
      * @param array<string, mixed> $request
      */
@@ -169,7 +189,13 @@ private function optionalPostalInfo(array $request): ?ContactPostalInfo
             );
         }
 
-        return $this->parsePostalInfo($postalInfo);
+        $parsedPostalInfo = $this->parsePostalInfo($postalInfo);
+
+        if ('' === \trim($parsedPostalInfo->name)) {
+            throw new \InvalidArgumentException('Contact postalInfo key "name" must be a non-empty string.');
+        }
+
+        return $parsedPostalInfo;
     }
 
     /**
@@ -199,16 +225,22 @@ private function parsePostalInfo(array $postalInfo): ContactPostalInfo
 
         return new ContactPostalInfo(
             $type,
-            $this->requireString(
-                $postalInfo,
-                'name',
-                'Contact postalInfo key "%s" must be a non-empty string.',
-            ),
+            $this->optionalStringAllowingEmpty($postalInfo, 'name'),
             $this->optionalNullableString($postalInfo, 'organization'),
             $this->parseAddress($address),
         );
     }
 
+    private function isLegalEntityCreateWithoutNaturalPersonName(
+        ?ContactExtension $extension,
+        ContactPostalInfo $postalInfo,
+    ): bool {
+        return null !== $extension
+            && '1' === $extension->isLegalEntity
+            && null !== $postalInfo->organization
+            && '' !== \trim($postalInfo->organization);
+    }
+
     /**
      * @param array<string, mixed> $address
      */
@@ -360,6 +392,20 @@ private function optionalNullableString(array $request, string $key): ?string
         return $value;
     }
 
+    /**
+     * @param array<string, mixed> $request
+     */
+    private function optionalStringAllowingEmpty(array $request, string $key): string
+    {
+        if (!\array_key_exists($key, $request) || !\is_string($request[$key])) {
+            throw new \InvalidArgumentException(
+                \sprintf('Contact postalInfo key "%s" must be a string.', $key),
+            );
+        }
+
+        return $request[$key];
+    }
+
     private function normalizeString(mixed $value, string $errorPattern, int $index): string
     {
         if (!\is_string($value) || '' === \trim($value)) {

src/Contact/ContactRequestFactory.php

@@ -45,6 +45,10 @@ public function mapCheckResponse(DomainCheckResponse $response): array
      *   updateDate: \DateTimeImmutable|null,
      *   expirationDate: \DateTimeImmutable|null,
      *   whoisPrivacy: bool,
+     *   isDomainVerified: bool,
+     *   domainVerifiedOn: \DateTimeImmutable|null,
+     *   domainVerificationRequestExpiresOn: \DateTimeImmutable|null,
+     *   isWhoisPrivacyPaid: bool,
      *   operationMode: string|null,
      *   notifyAdmin: bool,
      *   dnsSec: bool,
@@ -59,7 +63,11 @@ public function mapInfoResponse(DomainInfoResponse $response): array
             'createClientId' => $response->createClientId,
             'createDate' => $response->createDate,
             'dnsSec' => $response->dnsSec,
+            'domainVerificationRequestExpiresOn' => $response->domainVerificationRequestExpiresOn,
+            'domainVerifiedOn' => $response->domainVerifiedOn,
             'expirationDate' => $response->expirationDate,
+            'isDomainVerified' => $response->isDomainVerified,
+            'isWhoisPrivacyPaid' => $response->isWhoisPrivacyPaid,
             'name' => $response->name,
             'nameservers' => $this->mapNameservers($response->nameservers),
             'notifyAdmin' => $response->notifyAdmin,

src/Domain/DomainResponseMapper.php

@@ -156,6 +156,10 @@ public function check(string|array $request): array
      *   updateDate: \DateTimeImmutable|null,
      *   expirationDate: \DateTimeImmutable|null,
      *   whoisPrivacy: bool,
+     *   isDomainVerified: bool,
+     *   domainVerifiedOn: \DateTimeImmutable|null,
+     *   domainVerificationRequestExpiresOn: \DateTimeImmutable|null,
+     *   isWhoisPrivacyPaid: bool,
      *   operationMode: string|null,
      *   notifyAdmin: bool,
      *   dnsSec: bool,
@@ -328,13 +332,35 @@ public function update(array $request): array
     }
 
     /**
-     * @param array{
-     *   operation?: mixed,
-     *   name?: mixed,
-     *   period?: mixed,
-     *   periodUnit?: mixed,
-     *   authInfo?: mixed
-     * } $request
+     * Approves a domain transfer using the provided transfer code.
+     *
+     * @return array{
+     *   name: string|null,
+     *   transferStatus: string|null,
+     *   requestClientId: string|null,
+     *   requestDate: \DateTimeImmutable|null,
+     *   actionClientId: string|null,
+     *   actionDate: \DateTimeImmutable|null,
+     *   expirationDate: \DateTimeImmutable|null
+     * }
+     */
+    public function transfer(string $domain, string $transferCode): array
+    {
+        $name = $this->inputNormalizer->requireDomainName($domain);
+
+        if ('' === \trim($transferCode)) {
+            throw new \InvalidArgumentException('Domain transfer code must be a non-empty string.');
+        }
+
+        return $this->executeTransferOperation(
+            DomainTransferRequest::OPERATION_APPROVE,
+            $name,
+            $transferCode,
+        );
+    }
+
+    /**
+     * Starts the transfer flow and requests transfer code-related state from the registry.
      *
      * @return array{
      *   name: string|null,
@@ -346,15 +372,55 @@ public function update(array $request): array
      *   expirationDate: \DateTimeImmutable|null
      * }
      */
-    public function transfer(array $request): array
+    public function getCode(string $domain): array
+    {
+        return $this->executeTransferOperation(
+            DomainTransferRequest::OPERATION_REQUEST,
+            $this->inputNormalizer->requireDomainName($domain),
+        );
+    }
+
+    /**
+     * Queries current transfer state for a domain.
+     *
+     * @return array{
+     *   name: string|null,
+     *   transferStatus: string|null,
+     *   requestClientId: string|null,
+     *   requestDate: \DateTimeImmutable|null,
+     *   actionClientId: string|null,
+     *   actionDate: \DateTimeImmutable|null,
+     *   expirationDate: \DateTimeImmutable|null
+     * }
+     */
+    public function getState(string $domain): array
+    {
+        return $this->executeTransferOperation(
+            DomainTransferRequest::OPERATION_QUERY,
+            $this->inputNormalizer->requireDomainName($domain),
+        );
+    }
+
+    /**
+     * @return array{
+     *   name: string|null,
+     *   transferStatus: string|null,
+     *   requestClientId: string|null,
+     *   requestDate: \DateTimeImmutable|null,
+     *   actionClientId: string|null,
+     *   actionDate: \DateTimeImmutable|null,
+     *   expirationDate: \DateTimeImmutable|null
+     * }
+     */
+    private function executeTransferOperation(string $operation, string $name, ?string $authInfo = null): array
     {
         $xml = $this->transferRequestBuilder->build(
             new DomainTransferRequest(
-                $this->inputNormalizer->requireTransferOperation($request),
-                $this->inputNormalizer->requireName($request),
-                $this->inputNormalizer->optionalPositiveInt($request, 'period'),
-                $this->inputNormalizer->optionalPeriodUnit($request),
-                $this->inputNormalizer->optionalNullableString($request, 'authInfo'),
+                $operation,
+                $name,
+                null,
+                'y',
+                $authInfo,
             ),
             $this->tridGenerator->nextId(),
         );

src/Domain/DomainService.php

@@ -28,6 +28,10 @@ public function __construct(
         public readonly ?\DateTimeImmutable $updateDate,
         public readonly ?\DateTimeImmutable $expirationDate,
         public readonly bool $whoisPrivacy,
+        public readonly bool $isDomainVerified,
+        public readonly ?\DateTimeImmutable $domainVerifiedOn,
+        public readonly ?\DateTimeImmutable $domainVerificationRequestExpiresOn,
+        public readonly bool $isWhoisPrivacyPaid,
         public readonly ?string $operationMode,
         public readonly bool $notifyAdmin,
         public readonly bool $dnsSec,

src/Domain/Dto/DomainInfoResponse.php

@@ -153,11 +153,11 @@ private function parsePostalInfo(\DOMXPath $xpath): ?ContactPostalInfo
 
         $type = $this->normalizePostalInfoType($postalInfoNode);
 
-        $name = $this->firstRelativeNodeValue($xpath, 'contact:name', $postalInfoNode);
+        $name = $this->firstRelativeNodeValue($xpath, 'contact:name', $postalInfoNode) ?? '';
         $city = $this->firstRelativeNodeValue($xpath, 'contact:addr/contact:city', $postalInfoNode);
         $countryCode = $this->firstRelativeNodeValue($xpath, 'contact:addr/contact:cc', $postalInfoNode);
 
-        if (null === $name || null === $city || null === $countryCode) {
+        if (null === $city || null === $countryCode) {
             return null;
         }