add models for formatter with template

Author: JW Wesson

src/main/java/com/textkernel/tx/ApiEndpoints.java

@@ -98,4 +98,6 @@ private String sanitize(String indexOrDocId) throws IllegalArgumentException {
 
     String jobDescriptionGenerate() { return prefix(false) + "/job-description/generate"; }
     String jobDescriptionSuggestSkills() { return prefix(false) + "/job-description/suggest-skills"; }
+
+    String formatResume() { return prefix() + "/formatter/resume/template"; }
 }

src/main/java/com/textkernel/tx/TxClient.java

@@ -44,6 +44,7 @@
 import com.textkernel.tx.models.api.dataenrichment.skills.response.GetSkillsTaxonomyResponse;
 import com.textkernel.tx.models.api.dataenrichment.skills.response.LookupSkillCodesResponse;
 import com.textkernel.tx.models.api.dataenrichment.skills.response.NormalizeSkillsResponse;
+import com.textkernel.tx.models.api.formatter.FormatResumeRequest;
 import com.textkernel.tx.models.api.geocoding.*;
 import com.textkernel.tx.models.api.indexes.*;
 import com.textkernel.tx.models.api.jobdescription.GenerateJobRequest;
@@ -287,6 +288,17 @@ public GetAccountInfoResponse getAccountInfo() throws TxException {
         HttpResponse<GetAccountInfoResponse> response = executeRequest(apiRequest, GetAccountInfoResponse.class, getBodyIfDebug(apiRequest));
         return response.getData();
     }
+
+    public FormatResumeResponse formatResume(FormatResumeRequest request) throws TxException {
+        RequestBody body = createJsonBody(request);
+        Request apiRequest = new Request.Builder()
+            .url(_endpoints.formatResume())
+            .post(body)
+            .build();
+
+        HttpResponse<FormatResumeResponse> response = executeRequest(apiRequest, FormatResumeResponse.class, getBodyIfDebug(apiRequest));
+        return response.getData();
+    }
 
     /**
      * Parse a resume

src/main/java/com/textkernel/tx/models/api/formatter/FormatResumeRequest.java

@@ -0,0 +1,68 @@
+// Copyright © 2023 Textkernel BV. All rights reserved.
+// This file is provided for use by, or on behalf of, Textkernel licensees
+// within the terms of their license of Textkernel products or Textkernel customers
+// within the Terms of Service pertaining to the Textkernel SaaS products.
+
+package com.textkernel.tx.models.api.formatter;
+
+import java.io.IOException;
+import java.time.LocalDate;
+
+import com.textkernel.tx.models.Document;
+import com.textkernel.tx.models.resume.ParsedResume;
+
+/**
+* Request body for the Format Resume With Template endpoint
+*/
+public class FormatResumeRequest {
+    /**  The resume to use to populate the template */
+    public ParsedResume ResumeData;
+
+    /** 
+     * A base64-encoded string of the DOCX template document file bytes. This should use the standard 'base64'
+     * encoding as defined in RFC 4648 Section 4 (not the 'base64url' variant).
+     * <p>Java users can use {@link java.util.Base64#getEncoder()} and then {@link java.util.Base64.Encoder#encodeToString(byte[])}
+     * <p>For more information on creating custom templates, see
+     * <a href="https://developer.textkernel.com/tx-platform/v10/resume-formatter/creating-custom-templates/">here</a>
+     */
+    public String Template;
+
+    /** The output document type */
+    public OutputDocumentFormat OutputType;
+
+    /**
+     * Any data that the template needs that is not in the extracted CV data. For example:
+     * <pre>
+     *JSONObject myCustomData = new JSONObject();
+     *myCustomData.put("CandidateId", "12345");
+     *myCustomData.put("DateApplied", LocalDate.now());
+     *formatRequest.CustomData = myCustomData;
+     *</pre>
+     */
+    public Object CustomData;
+
+    /**
+     * Creates a request to use when calling the Resume Formatter endpoint with a provided template document.
+     * @param resume The resume to use to populate the template
+     * @param templatePath The path to the template DOCX file on disk
+     * @param docType The output document type
+     * @throws IOException if an error occurs reading the file contents
+     */
+    public FormatResumeRequest(ParsedResume resume, String templatePath, OutputDocumentFormat docType) throws IOException {
+        ResumeData = resume;
+        OutputType = docType;
+        Template = new Document(templatePath).getAsBase64();
+    }
+
+    /**
+     * Creates a request to use when calling the Resume Formatter endpoint with a provided template document.
+     * @param resume The resume to use to populate the template
+     * @param templateFileBytes The bytes of the template DOCX file
+     * @param docType The output document type
+     */
+    public FormatResumeRequest(ParsedResume resume, byte[] templateFileBytes, OutputDocumentFormat docType) {
+        ResumeData = resume;
+        OutputType = docType;
+        Template = new Document(templateFileBytes, LocalDate.now()).getAsBase64();
+    }
+}

src/main/java/com/textkernel/tx/models/api/formatter/FormatResumeResponse.java

@@ -0,0 +1,12 @@
+// Copyright © 2023 Textkernel BV. All rights reserved.
+// This file is provided for use by, or on behalf of, Textkernel licensees
+// within the terms of their license of Textkernel products or Textkernel customers
+// within the Terms of Service pertaining to the Textkernel SaaS products.
+
+package com.textkernel.tx.models.api.formatter;
+
+import com.textkernel.tx.models.api.ApiResponse;
+
+/** The response body for a Format Resume API call */
+public class FormatResumeResponse extends ApiResponse<FormatResumeResponseValue> {
+}

src/main/java/com/textkernel/tx/models/api/formatter/FormatResumeResponseValue.java

@@ -0,0 +1,20 @@
+// Copyright © 2023 Textkernel BV. All rights reserved.
+// This file is provided for use by, or on behalf of, Textkernel licensees
+// within the terms of their license of Textkernel products or Textkernel customers
+// within the Terms of Service pertaining to the Textkernel SaaS products.
+
+package com.textkernel.tx.models.api.formatter;
+
+import com.textkernel.tx.models.api.ApiResponse;
+
+/**
+* The {@link ApiResponse#Value} from a Format Resume response
+*/
+public class FormatResumeResponseValue {
+    /**
+     * The formatted resume document (either PDF or DOCX).
+     * This is a byte[] as a Base64-encoded string. You can use
+     * {@link java.util.Base64.Decoder#decode(String)} to get a byte[] to save to disk.
+     */
+    public String DocumentAsBase64String;
+}

src/main/java/com/textkernel/tx/models/api/formatter/OutputDocumentFormat.java

@@ -0,0 +1,14 @@
+// Copyright © 2023 Textkernel BV. All rights reserved.
+// This file is provided for use by, or on behalf of, Textkernel licensees
+// within the terms of their license of Textkernel products or Textkernel customers
+// within the Terms of Service pertaining to the Textkernel SaaS products.
+
+package com.textkernel.tx.models.api.formatter;
+
+/** The document type to be output by the formatter endpoint */
+public enum OutputDocumentFormat {
+    /** A Microsoft Word document */
+    DOCX,
+    /** A PDF document */
+    PDF
+}