feat(connector): add health.incidents

src/main/java/ai/pluggy/client/response/ConnectorIncident.java

@@ -0,0 +1,51 @@
+package ai.pluggy.client.response;
+
+import java.util.Date;
+
+import lombok.Builder;
+import lombok.Data;
+
+/**
+ * An incident affecting a connector right now, as published on
+ * https://status.pluggy.ai.
+ *
+ * <p>Only incidents active at this moment are listed: a scheduled maintenance
+ * appears once its window opens, not when it is announced.
+ */
+@Data
+@Builder
+public class ConnectorIncident {
+  String id;
+
+  /** Short, customer-facing summary. Safe to show to your own users. */
+  String title;
+
+  String description;
+
+  ConnectorIncidentType type;
+
+  /**
+   * Affected product line: {@code dados}, {@code pis}, {@code pis-agendado},
+   * {@code pixauto}, {@code smart} or {@code infra}.
+   */
+  String product;
+
+  /** {@code INCIDENT} for an unplanned problem, {@code MAINTENANCE} for a planned window. */
+  String kind;
+
+  /** {@code DEGRADED}, {@code PARTIAL_OUTAGE}, {@code MAJOR_OUTAGE} or {@code MAINTENANCE}. */
+  String severity;
+
+  /**
+   * {@code INVESTIGATING}, {@code IDENTIFIED}, {@code MONITORING} or
+   * {@code SCHEDULED}. Resolved incidents are not listed.
+   */
+  String state;
+
+  Date startedAt;
+
+  Date updatedAt;
+
+  /** Permalink to the full timeline and postmortem on the status page. */
+  String url;
+}

src/main/java/ai/pluggy/client/response/ConnectorIncidentType.java

@@ -0,0 +1,86 @@
+package ai.pluggy.client.response;
+
+import com.google.gson.annotations.SerializedName;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * What is broken, as opposed to how badly ({@code severity}) or how far along
+ * Pluggy is ({@code state}).
+ *
+ * <p>Use it to group the same problem across institutions, and to decide which
+ * incidents are worth showing your own users: a {@code SCHEDULED_MAINTENANCE}
+ * and a {@code TRANSACTIONS_MISSING} both read as "degraded" otherwise.
+ *
+ * <p>{@code OTHER} means Pluggy has not classified the incident, not that
+ * nothing is wrong. A value added server-side after this SDK release
+ * deserializes as {@code null}.
+ */
+@AllArgsConstructor
+public enum ConnectorIncidentType {
+
+  // Whether you can connect at all.
+  @SerializedName("CONNECTOR_UNAVAILABLE")
+  CONNECTOR_UNAVAILABLE("CONNECTOR_UNAVAILABLE"),
+
+  @SerializedName("CONNECTOR_DEGRADED")
+  CONNECTOR_DEGRADED("CONNECTOR_DEGRADED"),
+
+  @SerializedName("INSTITUTION_OUTAGE")
+  INSTITUTION_OUTAGE("INSTITUTION_OUTAGE"),
+
+  @SerializedName("SCHEDULED_MAINTENANCE")
+  SCHEDULED_MAINTENANCE("SCHEDULED_MAINTENANCE"),
+
+  // It answers, but the connection does not complete or does not refresh.
+  @SerializedName("CONSENT_ERROR")
+  CONSENT_ERROR("CONSENT_ERROR"),
+
+  @SerializedName("CONNECTION_NOT_UPDATING")
+  CONNECTION_NOT_UPDATING("CONNECTION_NOT_UPDATING"),
+
+  @SerializedName("PARTIAL_SUCCESS")
+  PARTIAL_SUCCESS("PARTIAL_SUCCESS"),
+
+  // It connects and syncs, but what comes back is wrong or incomplete.
+  @SerializedName("ACCOUNTS_MISSING")
+  ACCOUNTS_MISSING("ACCOUNTS_MISSING"),
+
+  @SerializedName("BALANCE_INCORRECT")
+  BALANCE_INCORRECT("BALANCE_INCORRECT"),
+
+  @SerializedName("TRANSACTIONS_MISSING")
+  TRANSACTIONS_MISSING("TRANSACTIONS_MISSING"),
+
+  @SerializedName("TRANSACTIONS_INCORRECT")
+  TRANSACTIONS_INCORRECT("TRANSACTIONS_INCORRECT"),
+
+  @SerializedName("TRANSACTIONS_INSTALLMENTS_ISSUE")
+  TRANSACTIONS_INSTALLMENTS_ISSUE("TRANSACTIONS_INSTALLMENTS_ISSUE"),
+
+  @SerializedName("INVESTMENTS_MISSING")
+  INVESTMENTS_MISSING("INVESTMENTS_MISSING"),
+
+  @SerializedName("INVESTMENTS_INCORRECT")
+  INVESTMENTS_INCORRECT("INVESTMENTS_INCORRECT"),
+
+  @SerializedName("IDENTITY_MISSING")
+  IDENTITY_MISSING("IDENTITY_MISSING"),
+
+  @SerializedName("HISTORICAL_DATA_MISSING")
+  HISTORICAL_DATA_MISSING("HISTORICAL_DATA_MISSING"),
+
+  // Pluggy's own platform, not the institution's.
+  @SerializedName("WEBHOOK_DELAY")
+  WEBHOOK_DELAY("WEBHOOK_DELAY"),
+
+  @SerializedName("PAYMENT_FAILURE")
+  PAYMENT_FAILURE("PAYMENT_FAILURE"),
+
+  @SerializedName("OTHER")
+  OTHER("OTHER");
+
+  @Getter
+  private String value;
+}

src/main/java/ai/pluggy/client/response/Health.java

@@ -1,5 +1,7 @@
 package ai.pluggy.client.response;
 
+import java.util.List;
+
 import lombok.Builder;
 import lombok.Data;
 
@@ -9,4 +11,14 @@ public class Health {
   ConnectorStatus status;
 
   String stage;
+
+  /**
+   * Incidents affecting this connector right now, worst first. Null when there
+   * are none, so its presence is the signal.
+   *
+   * <p>It describes the institution, not your own connections. {@link #status}
+   * answers "can I connect at all"; this answers "what is wrong" — a bank can
+   * be perfectly reachable and still be failing to return instalments.
+   */
+  List<ConnectorIncident> incidents;
 }