Added PDF retrieval for invoices including test (#7)

thalestomme · web-flow · commit c5071ae33c57 · 2026-01-24T18:53:41.000+01:00
* Added PDF retrieval for invoices including test
* resolved code review comments
diff --git a/pom.xml b/pom.xml
@@ -20,6 +20,12 @@
             <version>4.13.2</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.hamcrest</groupId>
+            <artifactId>hamcrest</artifactId>
+            <version>2.2</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
     <developers>
         <developer>
diff --git a/src/main/java/com/twikey/DocumentGateway.java b/src/main/java/com/twikey/DocumentGateway.java
@@ -3,6 +3,7 @@
 import com.twikey.callback.DocumentCallback;
 import com.twikey.modal.DocumentRequests;
 import com.twikey.modal.DocumentResponse;
+import com.twikey.modal.ResponseUtils;
 import org.json.JSONArray;
 import org.json.JSONObject;
 import org.json.JSONTokener;
@@ -332,19 +333,16 @@ public DocumentResponse.CustomerAccessResponse customerAccess(String mandateNumb
      */
     public DocumentResponse.PdfResponse retrievePdf(String mandateNumber) throws IOException, TwikeyClient.UserException {
         HttpRequest request = HttpRequest.newBuilder(twikeyClient.getUrl("/mandate/pdf?mndtId=" + mandateNumber))
-                .headers("Content-Type", HTTP_FORM_ENCODED)
+                .header("Accept", "application/pdf")
                 .headers("User-Agent", twikeyClient.getUserAgent())
                 .headers("Authorization", twikeyClient.getSessionToken())
                 .GET()
                 .build();
         HttpResponse<byte[]> response = twikeyClient.send(request, HttpResponse.BodyHandlers.ofByteArray());
         if (response.statusCode() == 200) {
-            String disposition = response.headers().firstValue("content-disposition").orElse("=unknown.pdf");
-            String[] parts = disposition.split("=");
-            String filename = null;
-            if (parts.length == 2) {
-                filename = parts[1].trim().replace("\"", "");
-            }
+            String filename = ResponseUtils.extractFilenameFromContentDisposition(response.headers())
+                    .orElse(mandateNumber + ".pdf");
+
             return new DocumentResponse.PdfResponse(response.body(), filename);
         } else {
             throw new TwikeyClient.UserException(apiError(response));
diff --git a/src/main/java/com/twikey/InvoiceGateway.java b/src/main/java/com/twikey/InvoiceGateway.java
@@ -3,12 +3,14 @@
 import com.twikey.callback.InvoiceCallback;
 import com.twikey.modal.InvoiceRequests;
 import com.twikey.modal.InvoiceResponse;
+import com.twikey.modal.ResponseUtils;
 import org.json.JSONArray;
 import org.json.JSONException;
 import org.json.JSONObject;
 import org.json.JSONTokener;
 
 import java.io.IOException;
+import java.io.InputStream;
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
 import java.nio.file.Path;
@@ -287,12 +289,12 @@ public InvoiceResponse.BulkInvoiceDetail batchDetails(String batchId) throws IOE
 
 
     /**
-     * Get updates about all mandates (new/updated/cancelled)
+     * Get updates about all invoice states (BOOKED, PENDING, EXPIRED, PAID)
      *
      * @param invoiceCallback Callback for every change
      * @param sideloads       items to include in the sideloading @link <a href="https://www.twikey.com/api/#invoice-feed">www.twikey.com/api/#invoice-feed</a>
      * @throws IOException                When a network issue happened
-     * @throws TwikeyClient.UserException When there was an issue while retrieving the mandates (eg. invalid apikey)
+     * @throws TwikeyClient.UserException When there was an issue while retrieving the invoice states (eg. invalid apikey)
      */
     public void feed(InvoiceCallback invoiceCallback, String... sideloads) throws IOException, TwikeyClient.UserException {
 
@@ -326,4 +328,56 @@ public void feed(InvoiceCallback invoiceCallback, String... sideloads) throws IO
             }
         } while (!isEmpty);
     }
+
+
+    /**
+     * See <a href="https://www.twikey.com/api/#retrieve-invoice-pdf">Twikey API - Retrieve Invoice PDF</a>
+     * <p>
+     * Retrieves the PDF for a specific invoice using its UUID. The API will return
+     * the raw PDF content along with the filename as set by the server.
+     * </p>
+     *
+     * @param request An {@link InvoiceRequests.InvoicePdfRequest} containing the invoice UUID.
+     * @return {@link InvoiceResponse.Pdf} A structured response object containing
+     *         the PDF content and filename.
+     * @throws IOException                If a network error occurs during the request.
+     * @throws TwikeyClient.UserException If the API returns an error response.
+     *
+     * <p>Example usage:</p>
+     * <pre>{@code
+     * InvoiceRequests.InvoicePdfRequest pdfRequest = new InvoiceRequests.InvoicePdfRequest("032f42b8-9afc-459d-b0f5-b81a85a69e95");
+     * InvoiceResponse.Pdf pdf = invoiceGateway.pdf(pdfRequest);
+     * byte[] content = pdf.getContent();
+     * String filename = pdf.getFilename();
+     * }</pre>
+     */
+    public InvoiceResponse.Pdf pdf(InvoiceRequests.InvoicePdfRequest request)
+            throws IOException, TwikeyClient.UserException {
+        HttpRequest httpRequest = HttpRequest.newBuilder(
+                        twikeyClient.getUrl("/invoice/%s/pdf".formatted(request.id()))
+                )
+                .header("Accept", "application/pdf")
+                .header("User-Agent", twikeyClient.getUserAgent())
+                .header("Authorization", twikeyClient.getSessionToken())
+                .GET()
+                .build();
+
+        HttpResponse<InputStream> response = twikeyClient.send(
+                httpRequest,
+                HttpResponse.BodyHandlers.ofInputStream()
+        );
+
+
+        if (response.statusCode() == 200) {
+            String filename = ResponseUtils.extractFilenameFromContentDisposition(response.headers())
+                    .orElse(request.id() + ".pdf");
+
+            return new InvoiceResponse.Pdf(response.body(), filename);
+        } else {
+            throw new TwikeyClient.UserException(apiError(response));
+        }
+    }
+
+
+
 }
diff --git a/src/main/java/com/twikey/modal/InvoiceRequests.java b/src/main/java/com/twikey/modal/InvoiceRequests.java
@@ -94,7 +94,7 @@ public CreateInvoiceRequest setLocale(String locale) {
         }
 
         /**
-         * Control whether or not an traansaction is created provided a signed mandate is available
+         * Control whether or not a transaction is created provided a signed mandate is available
          *
          * @param manual when true no transaction is created to accompany the invoice
          */
@@ -594,4 +594,28 @@ public JSONArray toRequest() {
         }
     }
 
+    /**
+     * InvoicePdfRequest represents a request to retrieve the PDF for a single invoice
+     * via the Twikey API.
+     *
+     * <p>This request only requires the invoice UUID. The API will return
+     * the raw PDF content and filename for the specified invoice.</p>
+     *
+     * <p>Example usage:</p>
+     * <pre>{@code
+     * InvoiceRequests.InvoicePdfRequest pdfRequest = new InvoiceRequests.InvoicePdfRequest("032f42b8-9afc-459d-b0f5-b81a85a69e95");
+     * InvoiceResponse.Pdf pdf = invoiceGateway.pdf(pdfRequest);
+     * byte[] content = pdf.getContent();
+     * String filename = pdf.getFilename();
+     * }</pre>
+     */
+    record InvoicePdfRequest(String id) {
+        public InvoicePdfRequest {
+            if (id == null || id.isEmpty()) {
+                throw new IllegalArgumentException("Invoice UUID is required");
+            }
+        }
+    }
+
+
 }
diff --git a/src/main/java/com/twikey/modal/InvoiceResponse.java b/src/main/java/com/twikey/modal/InvoiceResponse.java
@@ -4,6 +4,7 @@
 import org.json.JSONArray;
 import org.json.JSONObject;
 
+import java.io.InputStream;
 import java.util.HashMap;
 import java.util.Map;
 
@@ -167,4 +168,10 @@ public String toString() {
             return "BulkInvoiceDetail{id='%s', results='%d'}".formatted(id, details.size());
         }
     }
+
+    /**
+     * PDF class specifically for invoices
+     */
+    record Pdf(InputStream content, String filename) {}
+
 }
diff --git a/src/main/java/com/twikey/modal/RequestUtils.java b/src/main/java/com/twikey/modal/RequestUtils.java
@@ -6,6 +6,10 @@
 
 public class RequestUtils {
 
+    private RequestUtils() {
+        // prevent instantiation
+    }
+
     public static void putIfNotNull(Map<String, String> map, String key, Object value) {
         if (value != null) {
             String val = String.valueOf(value);
diff --git a/src/main/java/com/twikey/modal/ResponseUtils.java b/src/main/java/com/twikey/modal/ResponseUtils.java
@@ -0,0 +1,48 @@
+package com.twikey.modal;
+
+import java.net.http.HttpHeaders;
+import java.util.Optional;
+
+public final class ResponseUtils {
+
+    private ResponseUtils() {
+        // prevent instantiation
+    }
+
+    public static Optional<String> extractFilenameFromContentDisposition(HttpHeaders headers) {
+        return headers.firstValue("content-disposition")
+                .flatMap(ResponseUtils::parseContentDispositionFilename);
+    }
+
+    static Optional<String> parseContentDispositionFilename(String disposition) {
+        if (disposition == null || disposition.isBlank()) {
+            return Optional.empty();
+        }
+
+        for (String part : disposition.split(";")) {
+            part = part.trim();
+
+            if (part.startsWith("filename*=")) {
+                return Optional.of(decodeExtendedFilename(part.substring(9)));
+            }
+
+            if (part.startsWith("filename=")) {
+                return Optional.of(stripQuotes(part.substring(9)));
+            }
+        }
+
+        return Optional.empty();
+    }
+
+    private static String stripQuotes(String value) {
+        return value.replaceAll("^\"|\"$", "");
+    }
+
+    private static String decodeExtendedFilename(String value) {
+        int idx = value.indexOf("''");
+        if (idx > 0) {
+            return java.net.URLDecoder.decode(value.substring(idx + 2), java.nio.charset.StandardCharsets.UTF_8);
+        }
+        return value;
+    }
+}
diff --git a/src/test/java/com/twikey/InvoiceGatewayTest.java b/src/test/java/com/twikey/InvoiceGatewayTest.java
@@ -14,7 +14,13 @@
 import java.util.Objects;
 import java.util.stream.IntStream;
 
+import java.nio.file.Files;
+import java.nio.file.Paths;
+import java.util.Base64;
+
 import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+
 
 public class InvoiceGatewayTest {
 
@@ -116,4 +122,39 @@ public void getInvoicesAndDetails() throws IOException, TwikeyClient.UserExcepti
             System.out.printf("Invoice update with number %s %s euro %s%n", updatedInvoice.getNumber(), updatedInvoice.getAmount(), newState);
         }, "meta");
     }
+
+    @Test
+    public void testRetrieveInvoicePdf() throws IOException, TwikeyClient.UserException {
+        Assume.assumeTrue("APIKey and CT are set", apiKey != null && ct != null);
+
+        // 1. Create a new invoice (we can optionally attach a PDF)
+        String title = "PDF-Test-" + System.currentTimeMillis();
+        byte[] pdfBytes = Files.readAllBytes(Paths.get("src/test/resources/empty.pdf"));
+        String base64Pdf = Base64.getEncoder().encodeToString(pdfBytes);
+        InvoiceRequests.CreateInvoiceRequest request = new InvoiceRequests.CreateInvoiceRequest(
+                title,
+                100.0,
+                LocalDate.now().toString(),
+                LocalDate.now().plusMonths(1).toString(),
+                customer
+        ).setPdf(base64Pdf);
+
+        InvoiceResponse.Invoice createdInvoice = api.invoice().create(request);
+        String invoiceId = createdInvoice.getId();
+        assertNotNull("Invoice ID should not be null", invoiceId);
+
+        InvoiceRequests.InvoicePdfRequest pdfRequest = new InvoiceRequests.InvoicePdfRequest(invoiceId);
+        InvoiceResponse.Pdf pdf = api.invoice().pdf(pdfRequest);
+
+        assertNotNull("PDF object should not be null", pdf);
+        assertNotNull("PDF content should not be null", pdf.content());
+        assertNotNull("PDF filename should not be null", pdf.filename());
+
+        byte[] retrievedBytes = pdf.content().readAllBytes();
+        assertTrue("PDF should not be empty", retrievedBytes.length > 0);
+
+        System.out.printf("Retrieved PDF for invoice %s with filename: %s (%d bytes)%n",
+                invoiceId, pdf.filename(), retrievedBytes.length);
+    }
+
 }

Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,7 @@`
`4`	`4`	`import org.json.JSONArray;`
`5`	`5`	`import org.json.JSONObject;`
`6`	`6`
	`7`	`+import java.io.InputStream;`
`7`	`8`	`import java.util.HashMap;`
`8`	`9`	`import java.util.Map;`
`9`	`10`
`@@ -167,4 +168,10 @@ public String toString() {`
`167`	`168`	`return "BulkInvoiceDetail{id='%s', results='%d'}".formatted(id, details.size());`
`168`	`169`	`}`
`169`	`170`	`}`
	`171`	`+`
	`172`	`+ /**`
	`173`	`+ * PDF class specifically for invoices`
	`174`	`+ */`
	`175`	`+ record Pdf(InputStream content, String filename) {}`
	`176`	`+`
`170`	`177`	`}`