feat(FSADT1-777): Implement address look-up API (#481)

* Implement address look-up API

* Add log messages

* chore: fixing test

---------

Co-authored-by: Paulo Gomes da Cruz Junior <[email protected]>

backend/src/main/java/ca/bc/gov/app/configuration/ForestClientConfiguration.java

@@ -30,6 +30,8 @@ public class ForestClientConfiguration {
   private LegacyConfiguration legacy;
   @NestedConfigurationProperty
   private BcRegistryConfiguration bcregistry;
+  @NestedConfigurationProperty
+  private AddressCompleteConfiguration addressComplete;
 
   @Data
   @Builder
@@ -98,4 +100,13 @@ public static class BcRegistryConfiguration {
   public static class LegacyConfiguration {
     private String url;
   }
+
+  @Data
+  @Builder
+  @NoArgsConstructor
+  @AllArgsConstructor
+  public static class AddressCompleteConfiguration {
+    private String url;
+    private String apiKey;
+  }
 }

backend/src/main/java/ca/bc/gov/app/configuration/GlobalServiceConfiguration.java

@@ -9,11 +9,13 @@
 import ca.bc.gov.app.dto.bcregistry.BcRegistryFacetSearchResultsDto;
 import ca.bc.gov.app.dto.bcregistry.BcRegistryIdentificationDto;
 import ca.bc.gov.app.dto.bcregistry.ClientDetailsDto;
+import ca.bc.gov.app.dto.client.AddressCompleteFindDto;
+import ca.bc.gov.app.dto.client.AddressCompleteFindListDto;
+import ca.bc.gov.app.dto.client.AddressCompleteRetrieveDto;
+import ca.bc.gov.app.dto.client.AddressCompleteRetrieveListDto;
 import ca.bc.gov.app.dto.client.ClientAddressDto;
 import ca.bc.gov.app.dto.client.ClientBusinessInformationDto;
-import ca.bc.gov.app.dto.client.ClientCodeTypeDto;
 import ca.bc.gov.app.dto.client.ClientContactDto;
-import ca.bc.gov.app.dto.client.ClientDetailsAddressDto;
 import ca.bc.gov.app.dto.client.ClientLocationDto;
 import ca.bc.gov.app.dto.client.ClientLookUpDto;
 import ca.bc.gov.app.dto.client.ClientNameCodeDto;
@@ -35,11 +37,13 @@
 @Slf4j
 @RegisterReflectionForBinding({
     ValidationError.class,
+    AddressCompleteFindDto.class,
+    AddressCompleteFindListDto.class,
+    AddressCompleteRetrieveDto.class,
+    AddressCompleteRetrieveListDto.class,
     ClientAddressDto.class,
     ClientBusinessInformationDto.class,
-    ClientCodeTypeDto.class,
     ClientContactDto.class,
-    ClientDetailsAddressDto.class,
     ClientLocationDto.class,
     ClientLookUpDto.class,
     ClientNameCodeDto.class,
@@ -55,7 +59,6 @@
     ClientDetailsDto.class
 })
 public class GlobalServiceConfiguration {
-
   /**
    * Returns a configured instance of WebClient to communicate with the CHES API
    * based on the provided configuration.
@@ -113,4 +116,14 @@ public WebClient legacyApi(ForestClientConfiguration configuration) {
         .build();
   }
 
+  /**
+   * Returns a configured instance of WebClient for accessing the Canada Post AddressComplete API.
+   *
+   * @param configuration The configuration for the ForestClient.
+   * @return A configured instance of WebClient for accessing the AddressComplete API.
+   */
+  @Bean
+  public WebClient addressCompleteApi(ForestClientConfiguration configuration) {
+    return WebClient.builder().baseUrl(configuration.getAddressComplete().getUrl()).build();
+  }
 }

backend/src/main/java/ca/bc/gov/app/controller/client/ClientAddressController.java

@@ -0,0 +1,105 @@
+package ca.bc.gov.app.controller.client;
+
+import ca.bc.gov.app.dto.client.ClientAddressDto;
+import ca.bc.gov.app.dto.client.ClientNameCodeDto;
+import ca.bc.gov.app.service.client.ClientAddressService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.MediaType;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+
+@RestController
+@Slf4j
+@Tag(
+    name = "FSA Clients",
+    description = "The FSA Client endpoint, responsible for handling client data"
+)
+@RequestMapping(value = "/api/clients", produces = MediaType.APPLICATION_JSON_VALUE)
+@RequiredArgsConstructor
+public class ClientAddressController {
+
+  private final ClientAddressService clientAddressService;
+
+  @GetMapping("/addresses")
+  @Operation(
+      summary = "Autocomplete addresses",
+      responses = {
+          @ApiResponse(
+              responseCode = "200",
+              description = "Returns a list of possible addresses",
+              content = @Content(
+                  mediaType = MediaType.APPLICATION_JSON_VALUE,
+                  array = @ArraySchema(
+                      schema = @Schema(
+                          name = "NameCode",
+                          implementation = ClientNameCodeDto.class
+                      )
+                  )
+              )
+          )
+      }
+  )
+  public Flux<ClientNameCodeDto> findPossibleAddresses(
+      @Parameter(description =
+          "The name or ISO 2 or 3 character code for the country to search in, defaults to CA",
+          example = "UK")
+      @RequestParam(value = "country", required = false, defaultValue = "CA")
+      String country,
+
+      @Parameter(description =
+          "The maximum number of autocomplete suggestions to return, defaults to 7",
+          example = "7")
+      @RequestParam(value = "maxSuggestions", required = false, defaultValue = "7")
+      Integer maxSuggestions,
+
+      @Parameter(description = "The search term to find", example = "2701 ri")
+      @RequestParam(value = "searchTerm", required = true)
+      String searchTerm) {
+    return clientAddressService
+        .findPossibleAddresses(country, maxSuggestions, searchTerm);
+  }
+
+  @GetMapping("/address/{addressId}")
+  @Operation(
+      summary = "Retrieve address",
+      responses = {
+          @ApiResponse(
+              responseCode = "200",
+              description = "Returns an addresses",
+              content = @Content(
+                  mediaType = MediaType.APPLICATION_JSON_VALUE,
+                  array = @ArraySchema(
+                      schema = @Schema(
+                          name = "Address",
+                          implementation = ClientAddressDto.class
+                      )
+                  )
+              )
+          )
+      }
+  )
+  public Mono<ClientAddressDto> getAddress(
+      @Parameter(
+          description = """
+              The id of the address to retrieve the details for.
+               The id can be obtained through <b>/api/client/addresses<b> endpoint""",
+          example = "CA|CP|B|0000001"
+      )
+      @PathVariable String addressId) {
+    return clientAddressService
+        .getAddress(addressId);
+  }
+}

backend/src/main/java/ca/bc/gov/app/dto/client/AddressCompleteFindDto.java

@@ -0,0 +1,26 @@
+package ca.bc.gov.app.dto.client;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+@JsonIgnoreProperties(ignoreUnknown = true)
+public record AddressCompleteFindDto(
+    @JsonProperty("Id")
+    String id,
+    @JsonProperty("Text")
+    String text,
+    @JsonProperty("Description")
+    String description,
+
+    @JsonProperty("Next")
+    String next,
+
+    @JsonProperty("Error")
+    String error,
+
+    @JsonProperty("Cause")
+    String cause,
+
+    @JsonProperty("Resolution")
+    String resolution) implements AddressError {
+}

backend/src/main/java/ca/bc/gov/app/dto/client/AddressCompleteFindListDto.java

@@ -0,0 +1,11 @@
+package ca.bc.gov.app.dto.client;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.List;
+
+@JsonIgnoreProperties(ignoreUnknown = true)
+public record AddressCompleteFindListDto(
+    @JsonProperty("Items")
+    List<AddressCompleteFindDto> items) {
+}

backend/src/main/java/ca/bc/gov/app/dto/client/AddressCompleteRetrieveDto.java

@@ -0,0 +1,55 @@
+package ca.bc.gov.app.dto.client;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+@JsonIgnoreProperties(ignoreUnknown = true)
+public record AddressCompleteRetrieveDto(
+    @JsonProperty("Language")
+    String language,
+
+    @JsonProperty("City")
+    String city,
+
+    @JsonProperty("Province")
+    String province,
+
+    @JsonProperty("ProvinceName")
+    String provinceName,
+
+    @JsonProperty("CountryName")
+    String countryName,
+
+    @JsonProperty("CountryIso2")
+    String countryIso2,
+
+    @JsonProperty("PostalCode")
+    String postalCode,
+
+    @JsonProperty("Line1")
+    String line1,
+
+    @JsonProperty("Line2")
+    String line2,
+
+    @JsonProperty("Line3")
+    String line3,
+
+    @JsonProperty("Line4")
+    String line4,
+
+    @JsonProperty("Line5")
+    String line5,
+
+    @JsonProperty("Error")
+    String error,
+
+    @JsonProperty("Description")
+    String description,
+
+    @JsonProperty("Cause")
+    String cause,
+
+    @JsonProperty("Resolution")
+    String resolution) implements AddressError {
+}

backend/src/main/java/ca/bc/gov/app/dto/client/AddressCompleteRetrieveListDto.java

@@ -0,0 +1,11 @@
+package ca.bc.gov.app.dto.client;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.List;
+
+@JsonIgnoreProperties(ignoreUnknown = true)
+public record AddressCompleteRetrieveListDto(
+    @JsonProperty("Items")
+    List<AddressCompleteRetrieveDto> items) {
+}

backend/src/main/java/ca/bc/gov/app/dto/client/AddressError.java

@@ -0,0 +1,8 @@
+package ca.bc.gov.app.dto.client;
+
+public interface AddressError {
+  String error();
+  String description();
+  String cause();
+  String resolution();
+}

backend/src/main/java/ca/bc/gov/app/exception/AddressLookupException.java

@@ -0,0 +1,13 @@
+package ca.bc.gov.app.exception;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.web.bind.annotation.ResponseStatus;
+import org.springframework.web.server.ResponseStatusException;
+
+@ResponseStatus(HttpStatus.BAD_REQUEST)
+public class AddressLookupException extends ResponseStatusException {
+
+  public AddressLookupException(String error) {
+    super(HttpStatus.BAD_REQUEST, error);
+  }
+}