feat: add streaming download helpers

Author: javorosas

src/main/java/io/facturapi/http/FacturapiHttpClient.java

@@ -5,6 +5,7 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.facturapi.FacturapiException;
 import java.io.IOException;
+import java.io.InputStream;
 import java.net.URI;
 import java.net.URLEncoder;
 import java.net.http.HttpClient;
@@ -82,6 +83,14 @@ public byte[] postBytes(String path, Object body) {
     return requestBytes("POST", path, body);
   }
 
+  public InputStream getStream(String path) {
+    return requestStream("GET", path, null);
+  }
+
+  public InputStream postStream(String path, Object body) {
+    return requestStream("POST", path, body);
+  }
+
   private JsonNode requestJsonNode(
     String method,
     String path,
@@ -126,6 +135,42 @@ private byte[] requestBytes(String method, String path, Object body) {
     }
   }
 
+  private InputStream requestStream(String method, String path, Object body) {
+    try {
+      HttpRequest request = buildRequest(method, path, null, body, null);
+      HttpResponse<InputStream> response = httpClient.send(request, HttpResponse.BodyHandlers.ofInputStream());
+      int statusCode = response.statusCode();
+      if (statusCode < 200 || statusCode >= 300) {
+        byte[] responseBytes;
+        try (InputStream errorStream = response.body()) {
+          responseBytes = errorStream == null ? new byte[0] : errorStream.readAllBytes();
+        }
+        String bodyText = responseBytes.length == 0 ? "" : new String(responseBytes, StandardCharsets.UTF_8);
+        String message = "Request failed with status " + statusCode;
+        try {
+          JsonNode error = objectMapper.readTree(bodyText);
+          JsonNode messageNode = firstDefined(error, "message", "error", "detail");
+          if (messageNode != null && messageNode.isTextual()) {
+            message = messageNode.asText();
+          } else if (!bodyText.isEmpty()) {
+            message = bodyText;
+          }
+        } catch (Exception ignored) {
+          if (!bodyText.isEmpty()) {
+            message = bodyText;
+          }
+        }
+        throw new FacturapiException(message, statusCode, bodyText);
+      }
+      return response.body();
+    } catch (IOException e) {
+      throw new FacturapiException("I/O error when calling Facturapi API", e);
+    } catch (InterruptedException e) {
+      Thread.currentThread().interrupt();
+      throw new FacturapiException("Request interrupted", e);
+    }
+  }
+
   private <T> T convert(JsonNode node, Class<T> type) {
     if (type == Void.class) {
       return null;

src/main/java/io/facturapi/resources/InvoicesResource.java

@@ -5,6 +5,7 @@
 import io.facturapi.models.GenericResponse;
 import io.facturapi.models.Invoice;
 import io.facturapi.models.SearchResult;
+import java.io.InputStream;
 import java.util.Map;
 
 public class InvoicesResource extends BaseResource {
@@ -86,6 +87,17 @@ public byte[] downloadPdf(String id) {
     return client.getBytes("/invoices/" + id + "/pdf");
   }
 
+  /**
+   * Opens a streaming invoice PDF download.
+   *
+   * @param id Invoice id.
+   * @return PDF stream. Caller owns closing it.
+   * @see <a href="https://docs.facturapi.io/api#operation/downloadInvoice">API reference</a>
+   */
+  public InputStream downloadPdfStream(String id) {
+    return client.getStream("/invoices/" + id + "/pdf");
+  }
+
   /**
    * Downloads an invoice XML file.
    *
@@ -97,6 +109,17 @@ public byte[] downloadXml(String id) {
     return client.getBytes("/invoices/" + id + "/xml");
   }
 
+  /**
+   * Opens a streaming invoice XML download.
+   *
+   * @param id Invoice id.
+   * @return XML stream. Caller owns closing it.
+   * @see <a href="https://docs.facturapi.io/api#operation/downloadInvoice">API reference</a>
+   */
+  public InputStream downloadXmlStream(String id) {
+    return client.getStream("/invoices/" + id + "/xml");
+  }
+
   /**
    * Downloads an invoice ZIP package with PDF and XML.
    *
@@ -108,6 +131,17 @@ public byte[] downloadZip(String id) {
     return client.getBytes("/invoices/" + id + "/zip");
   }
 
+  /**
+   * Opens a streaming invoice ZIP download.
+   *
+   * @param id Invoice id.
+   * @return ZIP stream. Caller owns closing it.
+   * @see <a href="https://docs.facturapi.io/api#operation/downloadInvoice">API reference</a>
+   */
+  public InputStream downloadZipStream(String id) {
+    return client.getStream("/invoices/" + id + "/zip");
+  }
+
   /**
    * Downloads the cancellation receipt XML file.
    *
@@ -119,6 +153,17 @@ public byte[] downloadCancellationReceiptXml(String id) {
     return client.getBytes("/invoices/" + id + "/cancellation_receipt/xml");
   }
 
+  /**
+   * Opens a streaming cancellation receipt XML download.
+   *
+   * @param id Invoice id.
+   * @return XML stream. Caller owns closing it.
+   * @see <a href="https://docs.facturapi.io/api#operation/downloadCancellationReceiptXml">API reference</a>
+   */
+  public InputStream downloadCancellationReceiptXmlStream(String id) {
+    return client.getStream("/invoices/" + id + "/cancellation_receipt/xml");
+  }
+
   /**
    * Downloads the cancellation receipt PDF file.
    *
@@ -130,6 +175,17 @@ public byte[] downloadCancellationReceiptPdf(String id) {
     return client.getBytes("/invoices/" + id + "/cancellation_receipt/pdf");
   }
 
+  /**
+   * Opens a streaming cancellation receipt PDF download.
+   *
+   * @param id Invoice id.
+   * @return PDF stream. Caller owns closing it.
+   * @see <a href="https://docs.facturapi.io/api#operation/downloadCancellationReceiptXml">API reference</a>
+   */
+  public InputStream downloadCancellationReceiptPdfStream(String id) {
+    return client.getStream("/invoices/" + id + "/cancellation_receipt/pdf");
+  }
+
   /**
    * Updates a draft invoice.
    *

src/main/java/io/facturapi/resources/ReceiptsResource.java

@@ -6,6 +6,7 @@
 import io.facturapi.models.Invoice;
 import io.facturapi.models.Receipt;
 import io.facturapi.models.SearchResult;
+import java.io.InputStream;
 import java.util.Map;
 
 public class ReceiptsResource extends BaseResource {
@@ -107,4 +108,15 @@ public GenericResponse sendByEmail(String id, Map<String, Object> data) {
   public byte[] downloadPdf(String id) {
     return client.getBytes("/receipts/" + id + "/pdf");
   }
+
+  /**
+   * Opens a streaming receipt PDF download.
+   *
+   * @param id Receipt id.
+   * @return PDF stream. Caller owns closing it.
+   * @see <a href="https://docs.facturapi.io/api#operation/downloadReceiptPdf">API reference</a>
+   */
+  public InputStream downloadPdfStream(String id) {
+    return client.getStream("/receipts/" + id + "/pdf");
+  }
 }

src/main/java/io/facturapi/resources/RetentionsResource.java

@@ -5,6 +5,7 @@
 import io.facturapi.models.GenericResponse;
 import io.facturapi.models.Retention;
 import io.facturapi.models.SearchResult;
+import java.io.InputStream;
 import java.util.Map;
 
 public class RetentionsResource extends BaseResource {
@@ -85,6 +86,17 @@ public byte[] downloadPdf(String id) {
     return client.getBytes("/retentions/" + id + "/pdf");
   }
 
+  /**
+   * Opens a streaming retention PDF download.
+   *
+   * @param id Retention id.
+   * @return PDF stream. Caller owns closing it.
+   * @see <a href="https://docs.facturapi.io/api#operation/downloadRetention">API reference</a>
+   */
+  public InputStream downloadPdfStream(String id) {
+    return client.getStream("/retentions/" + id + "/pdf");
+  }
+
   /**
    * Downloads a retention XML file.
    *
@@ -96,6 +108,17 @@ public byte[] downloadXml(String id) {
     return client.getBytes("/retentions/" + id + "/xml");
   }
 
+  /**
+   * Opens a streaming retention XML download.
+   *
+   * @param id Retention id.
+   * @return XML stream. Caller owns closing it.
+   * @see <a href="https://docs.facturapi.io/api#operation/downloadRetention">API reference</a>
+   */
+  public InputStream downloadXmlStream(String id) {
+    return client.getStream("/retentions/" + id + "/xml");
+  }
+
   /**
    * Downloads a retention ZIP package with PDF and XML.
    *
@@ -106,4 +129,15 @@ public byte[] downloadXml(String id) {
   public byte[] downloadZip(String id) {
     return client.getBytes("/retentions/" + id + "/zip");
   }
+
+  /**
+   * Opens a streaming retention ZIP download.
+   *
+   * @param id Retention id.
+   * @return ZIP stream. Caller owns closing it.
+   * @see <a href="https://docs.facturapi.io/api#operation/downloadRetention">API reference</a>
+   */
+  public InputStream downloadZipStream(String id) {
+    return client.getStream("/retentions/" + id + "/zip");
+  }
 }

src/test/java/io/facturapi/FacturapiResourcesTest.java

@@ -15,6 +15,8 @@
 import io.facturapi.enums.Taxability;
 import io.facturapi.http.FacturapiConfig;
 import io.facturapi.models.Customer;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
 import java.time.Instant;
 import java.time.LocalDate;
 import java.util.Map;
@@ -41,6 +43,25 @@ void invoiceCreateUsesExpectedPath() {
     assertEquals("/v2/invoices?test=true", request.uri().getPath() + "?" + request.uri().getQuery());
   }
 
+  @Test
+  void invoicePdfCanBeStreamed() throws Exception {
+    StubHttpClient httpClient = new StubHttpClient();
+    httpClient.enqueueBinary(200, "PDF-CONTENT".getBytes(), "application/pdf");
+
+    Facturapi sdk = new Facturapi(
+      FacturapiConfig.builder("sk_test")
+        .httpClient(httpClient)
+        .build()
+    );
+
+    try (InputStream stream = sdk.invoices().downloadPdfStream("inv_1")) {
+      assertEquals("PDF-CONTENT", new String(stream.readAllBytes(), StandardCharsets.UTF_8));
+    }
+
+    var request = httpClient.requests().get(0);
+    assertEquals("/v2/invoices/inv_1/pdf", request.uri().getPath());
+  }
+
   @Test
   void sdkExposesAccessorBasedSurface() {
     Facturapi sdk = new Facturapi(

src/test/java/io/facturapi/StubHttpClient.java

@@ -1,6 +1,7 @@
 package io.facturapi;
 
 import java.io.IOException;
+import java.io.InputStream;
 import java.net.Authenticator;
 import java.net.CookieHandler;
 import java.net.ProxySelector;
@@ -10,13 +11,15 @@
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
 import java.time.Duration;
+import java.nio.ByteBuffer;
 import java.util.ArrayDeque;
 import java.util.ArrayList;
 import java.util.Deque;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Flow;
 import java.util.concurrent.Executor;
 import javax.net.ssl.SSLContext;
 import javax.net.ssl.SSLParameters;
@@ -108,7 +111,7 @@ public <T> HttpResponse<T> send(HttpRequest request, HttpResponse.BodyHandler<T>
       throw new IOException("No queued response");
     }
     @SuppressWarnings("unchecked")
-    T body = (T) queued.body;
+    T body = (T) buildBody(responseBodyHandler, queued.body, queued.statusCode, queued.headers);
     return new StubHttpResponse<>(request, queued.statusCode, body, queued.headers);
   }
 
@@ -188,4 +191,49 @@ public Version version() {
       return Version.HTTP_1_1;
     }
   }
+
+  private static <T> T buildBody(
+    HttpResponse.BodyHandler<T> responseBodyHandler,
+    byte[] body,
+    int statusCode,
+    Map<String, List<String>> headers
+  ) {
+    HttpResponse.ResponseInfo responseInfo = new ResponseInfo(statusCode, headers);
+    HttpResponse.BodySubscriber<T> subscriber = responseBodyHandler.apply(responseInfo);
+    subscriber.onSubscribe(new Flow.Subscription() {
+      @Override
+      public void request(long n) {}
+
+      @Override
+      public void cancel() {}
+    });
+    subscriber.onNext(List.of(ByteBuffer.wrap(body)));
+    subscriber.onComplete();
+    return subscriber.getBody().toCompletableFuture().join();
+  }
+
+  private static final class ResponseInfo implements HttpResponse.ResponseInfo {
+    private final int statusCode;
+    private final HttpHeaders headers;
+
+    ResponseInfo(int statusCode, Map<String, List<String>> headers) {
+      this.statusCode = statusCode;
+      this.headers = HttpHeaders.of(headers, (k, v) -> true);
+    }
+
+    @Override
+    public int statusCode() {
+      return statusCode;
+    }
+
+    @Override
+    public HttpHeaders headers() {
+      return headers;
+    }
+
+    @Override
+    public HttpClient.Version version() {
+      return HttpClient.Version.HTTP_1_1;
+    }
+  }
 }