feat(h005): support BTD download orders with service params and date range

Downloads sent the 3-letter order code as AdminOrderType with empty
StandardOrderParams, which EBICS 3.0 banks reject for customer data. This
mirrors the existing BTU upload path: optional EbicsDownloadParams produce
AdminOrderType=BTD with a BTDOrderParams/Service block, container type and an
optional DateRange.

Also fixes the date range that fetchFile(file, orderType, start, end) accepted
and dropped: without a service name the legacy order type is kept and the range
goes into StandardOrderParams. Behaviour without params is unchanged.

Dates are written as plain xs:date; passing a Calendar made XMLBeans append the
local offset (2026-08-10+02:00), which shifts the reported day for a bank in
another timezone.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: 2 people

src/main/java/org/kopi/ebics/client/EbicsClient.java

@@ -413,6 +413,17 @@ public void sendFile(File file, EbicsOrderType orderType) throws Exception {
 
     public void fetchFile(File file, User user, Product product, EbicsOrderType orderType,
         boolean isTest) throws IOException, EbicsException {
+        fetchFile(file, user, product, orderType, null, isTest);
+    }
+
+    /**
+     * Downloads a file from the bank.
+     *
+     * @param downloadParams optional EBICS 3.0 service parameters and report period; with a
+     *        service name set the order is sent as a BTD business transaction format order
+     */
+    public void fetchFile(File file, User user, Product product, EbicsOrderType orderType,
+        EbicsDownloadParams downloadParams, boolean isTest) throws IOException, EbicsException {
         FileTransfer transferManager;
         EbicsSession session = createSession(user, product);
         session.addSessionParam("FORMAT", "pain.xxx.cfonb160.dct");
@@ -425,7 +436,7 @@ public void fetchFile(File file, User user, Product product, EbicsOrderType orde
             configuration.getTransferTraceDirectory(user));
 
         try {
-            transferManager.fetchFile(orderType, file);
+            transferManager.fetchFile(orderType, downloadParams, file);
         } catch (NoDownloadDataAvailableException e) {
             // don't log this exception as an error, caller can decide how to handle
             throw e;
@@ -437,7 +448,8 @@ public void fetchFile(File file, User user, Product product, EbicsOrderType orde
 
     public void fetchFile(File file, EbicsOrderType orderType, Date start, Date end) throws IOException,
         EbicsException {
-        fetchFile(file, defaultUser, defaultProduct, orderType, false);
+        fetchFile(file, defaultUser, defaultProduct, orderType,
+            EbicsDownloadParams.dateRangeOnly(start, end), false);
     }
 
     /**

src/main/java/org/kopi/ebics/client/EbicsDownloadParams.java

@@ -0,0 +1,35 @@
+package org.kopi.ebics.client;
+
+import java.util.Date;
+
+/**
+ * Service parameters for an EBICS 3.0 (H005) BTD download order.
+ *
+ * <p>With a {@code serviceName} set, the request is sent as {@code AdminOrderType=BTD} with a
+ * {@code BTDOrderParams/Service} block. With {@code serviceName} left {@code null}, only the
+ * optional date range is applied and the legacy EBICS 2.x order type is kept, so existing
+ * callers keep their behaviour.
+ */
+public record EbicsDownloadParams(
+    String serviceName,
+    String scope,
+    String option,
+    String messageName,
+    String messageVersion,
+    String containerType,
+    Date startDate,
+    Date endDate) {
+
+    /** Date-range-only parameters for the legacy (non-BTD) download path. */
+    public static EbicsDownloadParams dateRangeOnly(Date startDate, Date endDate) {
+        if (startDate == null && endDate == null) {
+            return null;
+        }
+        return new EbicsDownloadParams(null, null, null, null, null, null, startDate, endDate);
+    }
+
+    /** Whether these parameters describe an EBICS 3.0 BTD business transaction format order. */
+    public boolean isBtd() {
+        return serviceName != null;
+    }
+}

src/main/java/org/kopi/ebics/client/FileTransfer.java

@@ -173,9 +173,27 @@ public void sendFile(ContentFactory factory,
   public void fetchFile(EbicsOrderType orderType,
                         File outputFile)
     throws IOException, EbicsException
+  {
+    fetchFile(orderType, null, outputFile);
+  }
+
+  /**
+   * Fetches a file of the given order type from the bank.
+   * This type of transfer will run until everything is processed.
+   * No transaction recovery is possible.
+   * @param orderType type of file to fetch
+   * @param downloadParams optional EBICS 3.0 service parameters and report period
+   * @param outputFile where to put the data
+   * @throws IOException communication error
+   * @throws EbicsException server generated error
+   */
+  public void fetchFile(EbicsOrderType orderType,
+                        EbicsDownloadParams downloadParams,
+                        File outputFile)
+    throws IOException, EbicsException
   {
     var sender = new HttpRequestSender(session);
-      var initializer = new DownloadInitializationRequestElement(session, orderType);
+      var initializer = new DownloadInitializationRequestElement(session, orderType, downloadParams);
     initializer.build();
     initializer.validate();
 

src/main/java/org/kopi/ebics/client/ParameterizedEbicsClientLauncher.java

@@ -20,11 +20,18 @@
 
 import java.io.File;
 import java.net.URL;
+import java.time.LocalDate;
+import java.time.ZoneId;
+import java.time.format.DateTimeParseException;
+import java.util.Date;
+import java.util.LinkedHashMap;
 import java.util.LinkedHashSet;
 import java.util.Locale;
+import java.util.Map;
 import java.util.Properties;
 import java.util.Set;
 import org.kopi.ebics.interfaces.EbicsBank;
+import org.kopi.ebics.interfaces.EbicsOrderType;
 import org.kopi.ebics.interfaces.EbicsPartner;
 import org.kopi.ebics.interfaces.PasswordCallback;
 import org.kopi.ebics.session.DefaultConfiguration;
@@ -41,9 +48,16 @@ public final class ParameterizedEbicsClientLauncher {
         "--ini",
         "--hia",
         "--hpb",
-        "--help"
+        "--help",
+        "--btd"
     );
 
+    /**
+     * EBICS 3.0 business transaction downloads always use the admin order type {@code BTD}; the
+     * business order is carried by the service parameters instead of the 3-letter code.
+     */
+    private static final EbicsOrderType BTD_ORDER_TYPE = () -> "BTD";
+
     private ParameterizedEbicsClientLauncher() {
     }
 
@@ -117,6 +131,20 @@ public static void main(String[] args) throws Exception {
             client.sendHPBRequest(user, product);
         }
 
+        if (parsedArguments.hasFlag("--btd")) {
+            EbicsDownloadParams downloadParams = btdDownloadParams(parsedArguments);
+            client.fetchFile(
+                new File(requireOutputPath(parsedArguments)),
+                user,
+                product,
+                BTD_ORDER_TYPE,
+                downloadParams,
+                Boolean.parseBoolean(env("EBICS_TEST_MODE", "false"))
+            );
+            client.quit();
+            return;
+        }
+
         String orderFlag = parsedArguments.firstOrderFlag();
         if (orderFlag != null) {
             OrderType orderType = OrderType.valueOf(orderFlag.substring(2).toUpperCase(Locale.ROOT));
@@ -129,16 +157,15 @@ public static void main(String[] args) throws Exception {
                     defaultUploadParams(user, orderType)
                 );
             } else if (parsedArguments.outputPath() != null) {
-                if (parsedArguments.startDate() != null || parsedArguments.endDate() != null) {
-                    System.err.println(
-                        "Date range arguments are ignored in parameterized mode for this order type."
-                    );
-                }
                 client.fetchFile(
                     new File(parsedArguments.outputPath()),
                     user,
                     product,
                     orderType,
+                    EbicsDownloadParams.dateRangeOnly(
+                        parseDate(parsedArguments.startDate(), "--start"),
+                        parseDate(parsedArguments.endDate(), "--end")
+                    ),
                     Boolean.parseBoolean(env("EBICS_TEST_MODE", "false"))
                 );
             }
@@ -149,12 +176,67 @@ public static void main(String[] args) throws Exception {
 
     private static void printUsage() {
         String usage = "Usage: ParameterizedEbicsClientLauncher [--create] [--ini] [--hia] [--hpb]"
-            + " [--<order>] [-i inputFile] [-o outputFile]\n"
+            + " [--<order>] [-i inputFile] [-o outputFile] [-s start] [-e end]\n"
+            + "EBICS 3.0 download: --btd --service <NAME> --scope <CC> --msg-name <name>"
+            + " --msg-version <vv> --container <XML|ZIP|SVC>"
+            + " [--option <OPT>] [-s YYYY-MM-DD] [-e YYYY-MM-DD] -o <file>\n"
+            + "  e.g. --btd --service EOP --scope CH --msg-name camt.053 --msg-version 08"
+            + " --container ZIP -o statement.zip\n"
             + "Required environment variables: EBICS_PASSWORD, EBICS_USER_ID, EBICS_PARTNER_ID,"
             + " EBICS_HOST_ID, EBICS_BANK_URL";
         System.out.println(usage);
     }
 
+    /**
+     * Builds the EBICS 3.0 service parameters for {@code --btd}. Fails fast on a missing mandatory
+     * value, so a half-filled order is never sent to the bank.
+     */
+    static EbicsDownloadParams btdDownloadParams(ParsedArguments parsedArguments) {
+        // A half date range would be dropped silently further down, which is exactly how a
+        // catch-up run loses the days it was supposed to fetch.
+        if ((parsedArguments.startDate() == null) != (parsedArguments.endDate() == null)) {
+            throw new IllegalArgumentException(
+                "Options --start and --end must be given together, a single one is ignored"
+                    + " by the bank request");
+        }
+        return new EbicsDownloadParams(
+            requireOption(parsedArguments.serviceName(), "--service"),
+            requireOption(parsedArguments.scope(), "--scope"),
+            parsedArguments.option(),
+            requireOption(parsedArguments.messageName(), "--msg-name"),
+            requireOption(parsedArguments.messageVersion(), "--msg-version"),
+            requireOption(parsedArguments.containerType(), "--container"),
+            parseDate(parsedArguments.startDate(), "--start"),
+            parseDate(parsedArguments.endDate(), "--end")
+        );
+    }
+
+    static String requireOutputPath(ParsedArguments parsedArguments) {
+        return requireOption(parsedArguments.outputPath(), "-o");
+    }
+
+    private static String requireOption(String value, String option) {
+        String normalized = normalize(value);
+        if (normalized == null) {
+            throw new IllegalArgumentException("Missing required option " + option + " for --btd");
+        }
+        return normalized;
+    }
+
+    private static Date parseDate(String value, String option) {
+        String normalized = normalize(value);
+        if (normalized == null) {
+            return null;
+        }
+        try {
+            return Date.from(LocalDate.parse(normalized)
+                .atStartOfDay(ZoneId.systemDefault()).toInstant());
+        } catch (DateTimeParseException e) {
+            throw new IllegalArgumentException(
+                "Option " + option + " expects a date as YYYY-MM-DD but was: " + normalized);
+        }
+    }
+
     private static EbicsUploadParams defaultUploadParams(User user, OrderType orderType) {
         if (orderType == OrderType.XE2) {
             var orderParams = new EbicsUploadParams.OrderParams(
@@ -290,27 +372,41 @@ static String normalize(String value) {
 
     static final class ParsedArguments {
         private final Set<String> flags = new LinkedHashSet<>();
+        private final Map<String, String> values;
         private final String inputPath;
         private final String outputPath;
         private final String startDate;
         private final String endDate;
 
         private ParsedArguments(
             Set<String> flags,
+            Map<String, String> values,
             String inputPath,
             String outputPath,
             String startDate,
             String endDate
         ) {
             this.flags.addAll(flags);
+            this.values = Map.copyOf(values);
             this.inputPath = inputPath;
             this.outputPath = outputPath;
             this.startDate = startDate;
             this.endDate = endDate;
         }
 
+        /** Value options of the EBICS 3.0 service block; each consumes the following argument. */
+        private static final Set<String> VALUE_OPTIONS = Set.of(
+            "--service",
+            "--scope",
+            "--option",
+            "--msg-name",
+            "--msg-version",
+            "--container"
+        );
+
         static ParsedArguments parse(String[] args) {
             Set<String> flags = new LinkedHashSet<>();
+            Map<String, String> values = new LinkedHashMap<>();
             String inputPath = null;
             String outputPath = null;
             String startDate = null;
@@ -337,12 +433,17 @@ static ParsedArguments parse(String[] args) {
                         endDate = requireValue(args, ++index, arg);
                         continue;
                     }
+                    String lowered = arg.toLowerCase(Locale.ROOT);
+                    if (VALUE_OPTIONS.contains(lowered)) {
+                        values.put(lowered, requireValue(args, ++index, arg));
+                        continue;
+                    }
                     if (arg.startsWith("--")) {
-                        flags.add(arg.toLowerCase(Locale.ROOT));
+                        flags.add(lowered);
                     }
                 }
             }
-            return new ParsedArguments(flags, inputPath, outputPath, startDate, endDate);
+            return new ParsedArguments(flags, values, inputPath, outputPath, startDate, endDate);
         }
 
         private static String requireValue(String[] args, int index, String option) {
@@ -393,5 +494,29 @@ String startDate() {
         String endDate() {
             return endDate;
         }
+
+        String serviceName() {
+            return values.get("--service");
+        }
+
+        String scope() {
+            return values.get("--scope");
+        }
+
+        String option() {
+            return values.get("--option");
+        }
+
+        String messageName() {
+            return values.get("--msg-name");
+        }
+
+        String messageVersion() {
+            return values.get("--msg-version");
+        }
+
+        String containerType() {
+            return values.get("--container");
+        }
     }
 }