Merge pull request firecrawl#3463 from firecrawl/devin/1777532789-fix-java-sdk-qa-issues

fix(java-sdk): reject explicitly empty API keys and add missing async lifecycle methods

Author: Chadha93

apps/java-sdk/build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 }
 
 group = "com.firecrawl"
-version = "1.3.0"
+version = "1.4.0"
 
 java {
     sourceCompatibility = JavaVersion.VERSION_11

apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java

@@ -902,6 +902,116 @@ public CompletableFuture<BrowserListResponse> listBrowsersAsync(String status) {
         return CompletableFuture.supplyAsync(() -> listBrowsers(status), asyncExecutor);
     }
 
+    /**
+     * Asynchronously starts a crawl job and returns immediately with the job reference.
+     *
+     * @param url     the URL to start crawling from
+     * @param options crawl configuration options
+     * @return a CompletableFuture that resolves to the CrawlResponse
+     */
+    public CompletableFuture<CrawlResponse> startCrawlAsync(String url, CrawlOptions options) {
+        return CompletableFuture.supplyAsync(() -> startCrawl(url, options), asyncExecutor);
+    }
+
+    /**
+     * Asynchronously gets the status of a crawl job.
+     *
+     * @param jobId the crawl job ID
+     * @return a CompletableFuture that resolves to the CrawlJob
+     */
+    public CompletableFuture<CrawlJob> getCrawlStatusAsync(String jobId) {
+        return CompletableFuture.supplyAsync(() -> getCrawlStatus(jobId), asyncExecutor);
+    }
+
+    /**
+     * Asynchronously cancels a crawl job.
+     *
+     * @param jobId the crawl job ID
+     * @return a CompletableFuture that resolves to the cancellation response
+     */
+    public CompletableFuture<Map<String, Object>> cancelCrawlAsync(String jobId) {
+        return CompletableFuture.supplyAsync(() -> cancelCrawl(jobId), asyncExecutor);
+    }
+
+    /**
+     * Asynchronously starts a batch scrape job and returns immediately with the job reference.
+     *
+     * @param urls    the URLs to scrape
+     * @param options batch scrape configuration options
+     * @return a CompletableFuture that resolves to the BatchScrapeResponse
+     */
+    public CompletableFuture<BatchScrapeResponse> startBatchScrapeAsync(List<String> urls, BatchScrapeOptions options) {
+        return CompletableFuture.supplyAsync(() -> startBatchScrape(urls, options), asyncExecutor);
+    }
+
+    /**
+     * Asynchronously gets the status of a batch scrape job.
+     *
+     * @param jobId the batch scrape job ID
+     * @return a CompletableFuture that resolves to the BatchScrapeJob
+     */
+    public CompletableFuture<BatchScrapeJob> getBatchScrapeStatusAsync(String jobId) {
+        return CompletableFuture.supplyAsync(() -> getBatchScrapeStatus(jobId), asyncExecutor);
+    }
+
+    /**
+     * Asynchronously cancels a batch scrape job.
+     *
+     * @param jobId the batch scrape job ID
+     * @return a CompletableFuture that resolves to the cancellation response
+     */
+    public CompletableFuture<Map<String, Object>> cancelBatchScrapeAsync(String jobId) {
+        return CompletableFuture.supplyAsync(() -> cancelBatchScrape(jobId), asyncExecutor);
+    }
+
+    /**
+     * Asynchronously starts an agent task and returns immediately with the job reference.
+     *
+     * @param options agent configuration options
+     * @return a CompletableFuture that resolves to the AgentResponse
+     */
+    public CompletableFuture<AgentResponse> startAgentAsync(AgentOptions options) {
+        return CompletableFuture.supplyAsync(() -> startAgent(options), asyncExecutor);
+    }
+
+    /**
+     * Asynchronously gets the status of an agent task.
+     *
+     * @param jobId the agent job ID
+     * @return a CompletableFuture that resolves to the AgentStatusResponse
+     */
+    public CompletableFuture<AgentStatusResponse> getAgentStatusAsync(String jobId) {
+        return CompletableFuture.supplyAsync(() -> getAgentStatus(jobId), asyncExecutor);
+    }
+
+    /**
+     * Asynchronously cancels an agent task.
+     *
+     * @param jobId the agent job ID
+     * @return a CompletableFuture that resolves to the cancellation response
+     */
+    public CompletableFuture<Map<String, Object>> cancelAgentAsync(String jobId) {
+        return CompletableFuture.supplyAsync(() -> cancelAgent(jobId), asyncExecutor);
+    }
+
+    /**
+     * Asynchronously gets concurrency info.
+     *
+     * @return a CompletableFuture that resolves to the ConcurrencyCheck
+     */
+    public CompletableFuture<ConcurrencyCheck> getConcurrencyAsync() {
+        return CompletableFuture.supplyAsync(this::getConcurrency, asyncExecutor);
+    }
+
+    /**
+     * Asynchronously gets credit usage.
+     *
+     * @return a CompletableFuture that resolves to the CreditUsage
+     */
+    public CompletableFuture<CreditUsage> getCreditUsageAsync() {
+        return CompletableFuture.supplyAsync(this::getCreditUsage, asyncExecutor);
+    }
+
     // ================================================================
     // INTERNAL POLLING HELPERS
     // ================================================================
@@ -1008,6 +1118,7 @@ private void sleep(int seconds) {
     public static final class Builder {
 
         private String apiKey;
+        private boolean apiKeyExplicitlySet;
         private String apiUrl = DEFAULT_API_URL;
         private long timeoutMs = DEFAULT_TIMEOUT_MS;
         private int maxRetries = DEFAULT_MAX_RETRIES;
@@ -1023,6 +1134,7 @@ private Builder() {}
          */
         public Builder apiKey(String apiKey) {
             this.apiKey = apiKey;
+            this.apiKeyExplicitlySet = true;
             return this;
         }
 
@@ -1098,6 +1210,10 @@ public Builder httpClient(OkHttpClient httpClient) {
 
         public FirecrawlClient build() {
             String resolvedKey = apiKey;
+            if (apiKeyExplicitlySet && (resolvedKey == null || resolvedKey.isBlank())) {
+                throw new FirecrawlException(
+                        "API key cannot be null or empty when explicitly provided.");
+            }
             if (resolvedKey == null || resolvedKey.isBlank()) {
                 resolvedKey = System.getenv("FIRECRAWL_API_KEY");
             }

apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.java

@@ -28,6 +28,13 @@ void testBuilderRequiresApiKey() {
         );
     }
 
+    @Test
+    void testBuilderRejectsExplicitNullApiKey() {
+        assertThrows(FirecrawlException.class, () ->
+                FirecrawlClient.builder().apiKey(null).build()
+        );
+    }
+
     @Test
     void testBuilderAcceptsApiKey() {
         // Should not throw — just validates construction