#92 Implement earnings call endpoints

docs/README.md

@@ -93,7 +93,7 @@ Copy of https://site.financialmodelingprep.com/developer/docs/stable#directory
 | ❌️ |   -   | `/symbol-change`                   |
 | ✅️ | 0.1.0 | `/etf-list`                        |
 | ❌️ |   -   | `/actively-trading-list`           |
-| ❌️ |   -   | `/earnings-transcript-list`        |
+| ✅️ | 0.3.0 | `/earnings-transcript-list`        |
 | ❌️ |   -   | `/available-exchanges`             |
 | ❌️ |   -   | `/available-sectors`               |
 | ❌️ |   -   | `/available-industries`            |
@@ -468,9 +468,9 @@ Copy of https://site.financialmodelingprep.com/developer/docs/stable#earnings-tr
 |    | Since | Endpoint                          |
 |:--:|:-----:|-----------------------------------|
 | ✅️ | 0.3.0 | `/earning-call-transcript-latest` |
-| ❌️ |   -   | `/earning-call-transcript`        |
-| ❌️ |   -   | `/earning-call-transcript-dates`  |
-| ❌️ |   -   | `/earnings-transcript-list`       |
+| ✅️ | 0.3.0 | `/earning-call-transcript`        |
+| ✅️ | 0.3.0 | `/earning-call-transcript-dates`  |
+| ✅️ | 0.3.0 | `/earnings-transcript-list`       |
 
 ### Senate
 

src/main/java/dev/sorn/fmp4j/clients/FmpEarningsClient.java

@@ -1,25 +1,64 @@
 package dev.sorn.fmp4j.clients;
 
+import static dev.sorn.fmp4j.types.FmpLimit.limit;
+import static dev.sorn.fmp4j.types.FmpPage.page;
+
 import dev.sorn.fmp4j.cfg.FmpConfig;
 import dev.sorn.fmp4j.http.FmpHttpClient;
-import dev.sorn.fmp4j.models.FmpLatestEarningsCallTranscript;
-import dev.sorn.fmp4j.services.FmpLatestEarningsCallTranscriptService;
+import dev.sorn.fmp4j.models.FmpEarningsCallTranscript;
+import dev.sorn.fmp4j.models.FmpEarningsCallTranscriptDate;
+import dev.sorn.fmp4j.models.FmpEarningsCallTranscriptLatest;
+import dev.sorn.fmp4j.models.FmpEarningsCallTranscriptList;
+import dev.sorn.fmp4j.services.FmpEarningsCallTranscriptDatesService;
+import dev.sorn.fmp4j.services.FmpEarningsCallTranscriptLatestService;
+import dev.sorn.fmp4j.services.FmpEarningsCallTranscriptListService;
+import dev.sorn.fmp4j.services.FmpEarningsCallTranscriptService;
 import dev.sorn.fmp4j.services.FmpService;
 import dev.sorn.fmp4j.types.FmpLimit;
 import dev.sorn.fmp4j.types.FmpPage;
+import dev.sorn.fmp4j.types.FmpQuarter;
+import dev.sorn.fmp4j.types.FmpSymbol;
+import dev.sorn.fmp4j.types.FmpYear;
+import java.util.Optional;
 
 public class FmpEarningsClient {
 
     // Alphabetical order
-    protected final FmpService<FmpLatestEarningsCallTranscript[]> fmpEarningsCallTranscriptService;
+    protected final FmpService<FmpEarningsCallTranscript[]> fmpEarningsCallTranscriptService;
+    protected final FmpService<FmpEarningsCallTranscriptDate[]> fmpEarningsCallTranscriptDatesService;
+    protected final FmpService<FmpEarningsCallTranscriptLatest[]> fmpEarningsCallTranscriptLatestService;
+    protected final FmpService<FmpEarningsCallTranscriptList[]> fmpEarningsCallTranscriptListService;
 
     public FmpEarningsClient(FmpConfig fmpConfig, FmpHttpClient fmpHttpClient) {
-        this.fmpEarningsCallTranscriptService = new FmpLatestEarningsCallTranscriptService(fmpConfig, fmpHttpClient);
+        this.fmpEarningsCallTranscriptService = new FmpEarningsCallTranscriptService(fmpConfig, fmpHttpClient);
+        this.fmpEarningsCallTranscriptDatesService =
+                new FmpEarningsCallTranscriptDatesService(fmpConfig, fmpHttpClient);
+        this.fmpEarningsCallTranscriptLatestService =
+                new FmpEarningsCallTranscriptLatestService(fmpConfig, fmpHttpClient);
+        this.fmpEarningsCallTranscriptListService = new FmpEarningsCallTranscriptListService(fmpConfig, fmpHttpClient);
     }
 
-    public synchronized FmpLatestEarningsCallTranscript[] transcripts(FmpLimit limit, FmpPage page) {
-        fmpEarningsCallTranscriptService.param("limit", limit);
-        fmpEarningsCallTranscriptService.param("page", page);
+    public synchronized FmpEarningsCallTranscript[] transcripts(
+            FmpSymbol symbol, FmpYear year, FmpQuarter quarter, Optional<FmpLimit> limit) {
+        fmpEarningsCallTranscriptService.param("symbol", symbol);
+        fmpEarningsCallTranscriptService.param("year", year);
+        fmpEarningsCallTranscriptService.param("quarter", quarter);
+        limit.ifPresent(l -> fmpEarningsCallTranscriptService.param("limit", l));
         return fmpEarningsCallTranscriptService.download();
     }
+
+    public synchronized FmpEarningsCallTranscriptDate[] dates(FmpSymbol symbol) {
+        fmpEarningsCallTranscriptDatesService.param("symbol", symbol);
+        return fmpEarningsCallTranscriptDatesService.download();
+    }
+
+    public synchronized FmpEarningsCallTranscriptLatest[] latest(Optional<FmpLimit> limit, Optional<FmpPage> page) {
+        fmpEarningsCallTranscriptLatestService.param("limit", limit.orElse(limit(100)));
+        fmpEarningsCallTranscriptLatestService.param("page", page.orElse(page(0)));
+        return fmpEarningsCallTranscriptLatestService.download();
+    }
+
+    public synchronized FmpEarningsCallTranscriptList[] list() {
+        return fmpEarningsCallTranscriptListService.download();
+    }
 }

src/main/java/dev/sorn/fmp4j/csv/FmpCsvDeserializer.java

@@ -6,7 +6,7 @@
 import com.fasterxml.jackson.core.json.JsonReadFeature;
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.dataformat.csv.CsvMapper;
-import dev.sorn.fmp4j.deserialize.FmpDeserializer;
+import dev.sorn.fmp4j.http.FmpDeserializer;
 import dev.sorn.fmp4j.json.FmpJsonModule;
 import java.io.IOException;
 import java.io.StringReader;

src/main/java/dev/sorn/fmp4j/exceptions/FmpInvalidQuarterException.java

@@ -0,0 +1,7 @@
+package dev.sorn.fmp4j.exceptions;
+
+public class FmpInvalidQuarterException extends FmpException {
+    public FmpInvalidQuarterException(String message, Object... args) {
+        super(message, args);
+    }
+}

src/main/java/dev/sorn/fmp4j/deserialize/FmpDeserializer.java → src/main/java/dev/sorn/fmp4j/http/FmpDeserializer.java

@@ -1,4 +1,4 @@
-package dev.sorn.fmp4j.deserialize;
+package dev.sorn.fmp4j.http;
 
 import com.fasterxml.jackson.core.type.TypeReference;
 

src/main/java/dev/sorn/fmp4j/json/FmpJsonDeserializer.java

@@ -5,7 +5,7 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.SerializationFeature;
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
-import dev.sorn.fmp4j.deserialize.FmpDeserializer;
+import dev.sorn.fmp4j.http.FmpDeserializer;
 import java.io.IOException;
 
 public final class FmpJsonDeserializer implements FmpDeserializer {

src/main/java/dev/sorn/fmp4j/models/FmpEarningsCallTranscript.java

@@ -0,0 +1,13 @@
+package dev.sorn.fmp4j.models;
+
+import dev.sorn.fmp4j.types.FmpPeriod;
+import dev.sorn.fmp4j.types.FmpSymbol;
+import dev.sorn.fmp4j.types.FmpYear;
+import java.io.Serial;
+import java.time.LocalDate;
+
+public record FmpEarningsCallTranscript(
+        FmpSymbol symbol, FmpPeriod period, FmpYear year, LocalDate date, String content) implements FmpModel {
+    @Serial
+    private static final long serialVersionUID = 1L;
+}

src/main/java/dev/sorn/fmp4j/models/FmpEarningsCallTranscriptDate.java

@@ -0,0 +1,12 @@
+package dev.sorn.fmp4j.models;
+
+import dev.sorn.fmp4j.types.FmpQuarter;
+import dev.sorn.fmp4j.types.FmpYear;
+import java.io.Serial;
+import java.time.LocalDate;
+
+public record FmpEarningsCallTranscriptDate(FmpQuarter quarter, FmpYear fiscalYear, LocalDate date)
+        implements FmpModel {
+    @Serial
+    private static final long serialVersionUID = 1L;
+}

src/main/java/dev/sorn/fmp4j/models/FmpLatestEarningsCallTranscript.java → src/main/java/dev/sorn/fmp4j/models/FmpEarningsCallTranscriptLatest.java

@@ -6,7 +6,7 @@
 import java.io.Serial;
 import java.time.LocalDate;
 
-public record FmpLatestEarningsCallTranscript(LocalDate date, FmpSymbol symbol, FmpYear fiscalYear, FmpPeriod period)
+public record FmpEarningsCallTranscriptLatest(FmpSymbol symbol, FmpPeriod period, FmpYear fiscalYear, LocalDate date)
         implements FmpModel {
     @Serial
     private static final long serialVersionUID = 1L;

src/main/java/dev/sorn/fmp4j/models/FmpEarningsCallTranscriptList.java

@@ -0,0 +1,10 @@
+package dev.sorn.fmp4j.models;
+
+import dev.sorn.fmp4j.types.FmpSymbol;
+import java.io.Serial;
+
+public record FmpEarningsCallTranscriptList(FmpSymbol symbol, String companyName, Integer noOfTranscripts)
+        implements FmpModel {
+    @Serial
+    private static final long serialVersionUID = 1L;
+}

src/main/java/dev/sorn/fmp4j/services/FmpEarningsCallTranscriptDatesService.java

@@ -0,0 +1,30 @@
+package dev.sorn.fmp4j.services;
+
+import static dev.sorn.fmp4j.json.FmpJsonUtils.typeRef;
+
+import dev.sorn.fmp4j.cfg.FmpConfig;
+import dev.sorn.fmp4j.http.FmpHttpClient;
+import dev.sorn.fmp4j.models.FmpEarningsCallTranscriptDate;
+import dev.sorn.fmp4j.types.FmpSymbol;
+import java.util.Map;
+
+public class FmpEarningsCallTranscriptDatesService extends FmpService<FmpEarningsCallTranscriptDate[]> {
+    public FmpEarningsCallTranscriptDatesService(FmpConfig cfg, FmpHttpClient http) {
+        super(cfg, http, typeRef(FmpEarningsCallTranscriptDate[].class));
+    }
+
+    @Override
+    protected String relativeUrl() {
+        return "/earning-call-transcript-dates";
+    }
+
+    @Override
+    protected Map<String, Class<?>> requiredParams() {
+        return Map.of("symbol", FmpSymbol.class);
+    }
+
+    @Override
+    protected Map<String, Class<?>> optionalParams() {
+        return Map.of();
+    }
+}

src/main/java/dev/sorn/fmp4j/services/FmpLatestEarningsCallTranscriptService.java → src/main/java/dev/sorn/fmp4j/services/FmpEarningsCallTranscriptLatestService.java

@@ -4,14 +4,14 @@
 
 import dev.sorn.fmp4j.cfg.FmpConfig;
 import dev.sorn.fmp4j.http.FmpHttpClient;
-import dev.sorn.fmp4j.models.FmpLatestEarningsCallTranscript;
+import dev.sorn.fmp4j.models.FmpEarningsCallTranscriptLatest;
 import dev.sorn.fmp4j.types.FmpLimit;
 import dev.sorn.fmp4j.types.FmpPage;
 import java.util.Map;
 
-public class FmpLatestEarningsCallTranscriptService extends FmpService<FmpLatestEarningsCallTranscript[]> {
-    public FmpLatestEarningsCallTranscriptService(FmpConfig cfg, FmpHttpClient http) {
-        super(cfg, http, typeRef(FmpLatestEarningsCallTranscript[].class));
+public class FmpEarningsCallTranscriptLatestService extends FmpService<FmpEarningsCallTranscriptLatest[]> {
+    public FmpEarningsCallTranscriptLatestService(FmpConfig cfg, FmpHttpClient http) {
+        super(cfg, http, typeRef(FmpEarningsCallTranscriptLatest[].class));
     }
 
     @Override
@@ -21,11 +21,11 @@ protected String relativeUrl() {
 
     @Override
     protected Map<String, Class<?>> requiredParams() {
-        return Map.of("limit", FmpLimit.class, "page", FmpPage.class);
+        return Map.of();
     }
 
     @Override
     protected Map<String, Class<?>> optionalParams() {
-        return Map.of();
+        return Map.of("limit", FmpLimit.class, "page", FmpPage.class);
     }
 }

src/main/java/dev/sorn/fmp4j/services/FmpEarningsCallTranscriptListService.java

@@ -0,0 +1,29 @@
+package dev.sorn.fmp4j.services;
+
+import static dev.sorn.fmp4j.json.FmpJsonUtils.typeRef;
+
+import dev.sorn.fmp4j.cfg.FmpConfig;
+import dev.sorn.fmp4j.http.FmpHttpClient;
+import dev.sorn.fmp4j.models.FmpEarningsCallTranscriptList;
+import java.util.Map;
+
+public class FmpEarningsCallTranscriptListService extends FmpService<FmpEarningsCallTranscriptList[]> {
+    public FmpEarningsCallTranscriptListService(FmpConfig cfg, FmpHttpClient http) {
+        super(cfg, http, typeRef(FmpEarningsCallTranscriptList[].class));
+    }
+
+    @Override
+    protected String relativeUrl() {
+        return "/earnings-transcript-list";
+    }
+
+    @Override
+    protected Map<String, Class<?>> requiredParams() {
+        return Map.of();
+    }
+
+    @Override
+    protected Map<String, Class<?>> optionalParams() {
+        return Map.of();
+    }
+}

src/main/java/dev/sorn/fmp4j/services/FmpEarningsCallTranscriptService.java

@@ -0,0 +1,33 @@
+package dev.sorn.fmp4j.services;
+
+import static dev.sorn.fmp4j.json.FmpJsonUtils.typeRef;
+
+import dev.sorn.fmp4j.cfg.FmpConfig;
+import dev.sorn.fmp4j.http.FmpHttpClient;
+import dev.sorn.fmp4j.models.FmpEarningsCallTranscript;
+import dev.sorn.fmp4j.types.FmpLimit;
+import dev.sorn.fmp4j.types.FmpQuarter;
+import dev.sorn.fmp4j.types.FmpSymbol;
+import dev.sorn.fmp4j.types.FmpYear;
+import java.util.Map;
+
+public class FmpEarningsCallTranscriptService extends FmpService<FmpEarningsCallTranscript[]> {
+    public FmpEarningsCallTranscriptService(FmpConfig cfg, FmpHttpClient http) {
+        super(cfg, http, typeRef(FmpEarningsCallTranscript[].class));
+    }
+
+    @Override
+    protected String relativeUrl() {
+        return "/earning-call-transcript";
+    }
+
+    @Override
+    protected Map<String, Class<?>> requiredParams() {
+        return Map.of("symbol", FmpSymbol.class, "year", FmpYear.class, "quarter", FmpQuarter.class);
+    }
+
+    @Override
+    protected Map<String, Class<?>> optionalParams() {
+        return Map.of("limit", FmpLimit.class);
+    }
+}

src/main/java/dev/sorn/fmp4j/types/FmpQuarter.java

@@ -0,0 +1,74 @@
+package dev.sorn.fmp4j.types;
+
+import static java.lang.String.valueOf;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import dev.sorn.fmp4j.exceptions.FmpInvalidQuarterException;
+import java.io.Serial;
+
+public class FmpQuarter implements Comparable<FmpQuarter>, FmpValueObject<Integer> {
+    public static final int MIN_QUARTER_VALUE = 1;
+    public static final int MAX_QUARTER_VALUE = 4;
+    public static final FmpQuarter Q1 = new FmpQuarter(1);
+    public static final FmpQuarter Q2 = new FmpQuarter(2);
+    public static final FmpQuarter Q3 = new FmpQuarter(3);
+    public static final FmpQuarter Q4 = new FmpQuarter(4);
+    private final int value;
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private FmpQuarter(int value) {
+        if (value < MIN_QUARTER_VALUE) {
+            throw new FmpInvalidQuarterException(
+                    "[%d] is below the minimum allowed value [%d]", value, MIN_QUARTER_VALUE);
+        }
+        if (value > MAX_QUARTER_VALUE) {
+            throw new FmpInvalidQuarterException(
+                    "[%d] exceeds the maximum allowed value [%d]", value, MAX_QUARTER_VALUE);
+        }
+        this.value = value;
+    }
+
+    @JsonCreator
+    public static FmpQuarter quarter(int value) {
+        return new FmpQuarter(value);
+    }
+
+    @Override
+    public Integer value() {
+        return value;
+    }
+
+    @Override
+    public String toString() {
+        return valueOf(value);
+    }
+
+    @Override
+    public int hashCode() {
+        return value;
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj) {
+            return true;
+        }
+        if (obj == null) {
+            return false;
+        }
+        if (!(obj instanceof FmpQuarter that)) {
+            return false;
+        }
+        return this.value == that.value;
+    }
+
+    @Override
+    public int compareTo(FmpQuarter that) {
+        if (that == null) {
+            throw new FmpInvalidQuarterException("'that.value' is required");
+        }
+        return Integer.compare(this.value, that.value);
+    }
+}