feat: add a generic API request interface

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: Justintime50

src/main/java/com/easypost/service/EasyPostClient.java

@@ -1,13 +1,17 @@
 package com.easypost.service;
 
+import java.util.Map;
 import java.util.function.Function;
 
 import com.easypost.Constants;
+import com.easypost.exception.EasyPostException;
 import com.easypost.exception.General.MissingParameterError;
 import com.easypost.hooks.RequestHook;
 import com.easypost.hooks.RequestHookResponses;
 import com.easypost.hooks.ResponseHook;
 import com.easypost.hooks.ResponseHookResponses;
+import com.easypost.http.Requestor;
+import com.easypost.http.Requestor.RequestMethod;
 
 import lombok.Getter;
 
@@ -215,4 +219,23 @@ public String getApiVersion() {
     public String getApiBase() {
         return apiBase;
     }
+
+    /**
+     * Make an API call to the EasyPost API.
+     *
+     * This public, generic interface is useful for making arbitrary API calls to the EasyPost API that
+     * are not yet supported by the client library's services. When possible, the service for your use case
+     * should be used instead as it provides a more convenient and higher-level interface depending on the endpoint.
+     *
+     * @param method   The HTTP method to use for the request.
+     * @param endpoint The endpoint to call (e.g., "/addresses").
+     * @param params   The parameters to send with the request.
+     * @return A Map containing the API response.
+     * @throws EasyPostException when the request fails.
+     */
+    @SuppressWarnings("unchecked")
+    public Map<String, Object> makeApiCall(RequestMethod method, String endpoint, Map<String, Object> params)
+            throws EasyPostException {
+        return Requestor.request(method, endpoint, params, Map.class, this);
+    }
 }

src/test/cassettes/client/make_api_call.json

@@ -0,0 +1,50 @@
+package com.easypost;
+
+import com.easypost.exception.EasyPostException;
+import com.easypost.http.Requestor.RequestMethod;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+public final class EasyPostClientTest {
+    private static TestUtils.VCR vcr;
+
+    /**
+     * Set up the testing environment for this file.
+     *
+     * @throws EasyPostException when the request fails.
+     */
+    @BeforeAll
+    public static void setup() throws EasyPostException {
+        vcr = new TestUtils.VCR("client", TestUtils.ApiKey.TEST);
+    }
+
+    /**
+     * Test making a generic API call.
+     *
+     * @throws EasyPostException when the request fails.
+     */
+    @Test
+    public void testMakeApiCall() throws EasyPostException {
+        vcr.setUpTest("make_api_call");
+
+        Map<String, Object> params = new HashMap<>();
+        params.put("page_size", 1);
+
+        Map<String, Object> response = vcr.client.makeApiCall(RequestMethod.GET, "addresses", params);
+
+        assertNotNull(response);
+        List<?> addresses = (List<?>) response.get("addresses");
+        assertNotNull(addresses);
+        assertEquals(1, addresses.size());
+
+        Map<String, Object> firstAddress = (Map<String, Object>) addresses.get(0);
+        assertEquals("Address", firstAddress.get("object"));
+    }
+}