Add resproxy API support

Add getResproxy method to IPinfo for looking up residential proxy
information for IP addresses.

The resproxy API endpoint returns:
- ip: The IP address
- last_seen: Last recorded date when the proxy was active
- percent_days_seen: Percentage of days active in the last 7-day period
- service: Name of the residential proxy service

Author: silvanocerza

.phpactor.json

@@ -0,0 +1,4 @@
+{
+    "$schema": "/phpactor.schema.json",
+    "php_code_sniffer.enabled": true
+}

src/IPinfo.php

@@ -254,6 +254,57 @@ public function getRequestDetails(string $ip_address)
         return $raw_details;
     }
 
+    /**
+     * Get residential proxy information for an IP address.
+     * @param string $ip_address IP address to look up.
+     * @return array Resproxy data containing ip, last_seen, percent_days_seen, service.
+     * @throws IPinfoException
+     */
+    public function getResproxy(string $ip_address)
+    {
+        $cacheKey = "resproxy/$ip_address";
+
+        if ($this->cache != null) {
+            $cachedRes = $this->cache->get($this->cacheKey($cacheKey));
+            if ($cachedRes != null) {
+                // The cache may modify the 'ip' field for IPv6 normalization,
+                // but for resproxy the key contains a prefix, so restore original IP
+                $cachedRes['ip'] = $ip_address;
+                return $cachedRes;
+            }
+        }
+
+        $url = self::API_URL . "/resproxy/$ip_address";
+
+        try {
+            $response = $this->http_client->request('GET', $url);
+        } catch (GuzzleException $e) {
+            throw new IPinfoException($e->getMessage());
+        } catch (Exception $e) {
+            throw new IPinfoException($e->getMessage());
+        }
+
+        if ($response->getStatusCode() == self::STATUS_CODE_QUOTA_EXCEEDED) {
+            throw new IPinfoException('IPinfo request quota exceeded.');
+        } elseif ($response->getStatusCode() >= 400) {
+            throw new IPinfoException(
+                'Exception: ' .
+                    json_encode([
+                        'status' => $response->getStatusCode(),
+                        'reason' => $response->getReasonPhrase(),
+                    ]),
+            );
+        }
+
+        $details = json_decode($response->getBody(), true);
+
+        if ($this->cache != null) {
+            $this->cache->set($this->cacheKey($cacheKey), $details);
+        }
+
+        return $details;
+    }
+
     /**
      * Gets a URL to a map on https://ipinfo.io/map given a list of IPs (max
      * 500,000).

tests/IPinfoTest.php

@@ -405,4 +405,36 @@ public function testIPv6NotationsCaching()
         $normalized_ip = inet_ntop(inet_pton($standard_ip));
         $h->getDetails($normalized_ip);
     }
+
+    public function testResproxy()
+    {
+        $tok = getenv('IPINFO_TOKEN');
+        if (!$tok) {
+            $this->markTestSkipped('IPINFO_TOKEN env var required');
+        }
+
+        $h = new IPinfo($tok);
+        $ip = '175.107.211.204';
+
+        // test multiple times for cache hits
+        for ($i = 0; $i < 5; $i++) {
+            $res = $h->getResproxy($ip);
+            $this->assertEquals($res['ip'], $ip);
+            $this->assertNotNull($res['last_seen']);
+            $this->assertNotNull($res['percent_days_seen']);
+            $this->assertNotNull($res['service']);
+        }
+    }
+
+    public function testResproxyEmpty()
+    {
+        $tok = getenv("IPINFO_TOKEN");
+        if (!$tok) {
+            $this->markTestSkipped("IPINFO_TOKEN env var required");
+        }
+
+        $h = new IPinfo($tok);
+        $res = $h->getResproxy("8.8.8.8");
+        $this->assertEquals($res, []);
+    }
 }