feat (DEVEXP-211): Support Numbers webhooks

client/src/main/com/sinch/sdk/domains/numbers/CallbackConfigurationService.java

@@ -8,7 +8,7 @@
  * Callback Configuration Service
  *
  * @see <a
- *     href="https://developers.sinch.com/docs/numbers/api-reference/callbacks-numbers/tag/Callback-Configuration/">https://developers.sinch.com/docs/numbers/api-reference/callbacks-numbers/tag/Callback-Configuration/</a>
+ *     href="https://developers.sinch.com/docs/numbers/api-reference/numbers/tag/Callbacks/">https://developers.sinch.com/docs/numbers/api-reference/numbers/tag/Callbacks/</a>
  */
 public interface CallbackConfigurationService {
 

client/src/main/com/sinch/sdk/domains/numbers/NumbersService.java

@@ -40,4 +40,12 @@ public interface NumbersService {
    * @since 1.0
    */
   CallbackConfigurationService callback();
+
+  /**
+   * Webhooks helpers instance
+   *
+   * @return instance service related to webhooks helpers
+   * @since 1.0
+   */
+  WebHooksService webhooks();
 }

client/src/main/com/sinch/sdk/domains/numbers/WebHooksService.java

@@ -0,0 +1,28 @@
+package com.sinch.sdk.domains.numbers;
+
+import com.sinch.sdk.core.exceptions.ApiMappingException;
+import com.sinch.sdk.domains.numbers.models.webhooks.EventNotification;
+
+/**
+ * Webhooks service
+ *
+ * <p>Callback events are used to get notified about Numbers usage according to your configured
+ * callback URL
+ *
+ * <p>see <a
+ * href="https://developers.sinch.com/docs/numbers/api-reference/numbers/tag/Callbacks/#tag/Callbacks/operation/ImportedNumberService_EventsCallback">https://developers.sinch.com/docs/numbers/api-reference/numbers/tag/Callbacks/#tag/Callbacks/operation/ImportedNumberService_EventsCallback</a>
+ *
+ * @since 1.0
+ */
+public interface WebHooksService {
+
+  /**
+   * This function can be called to deserialize received payload onto callback. Function return Java
+   * class instance from un-serialized payload
+   *
+   * @param jsonPayload Received payload to be un-serialized
+   * @return The decoded event notification instance class
+   * @since 1.0
+   */
+  EventNotification unserializeEventNotification(String jsonPayload) throws ApiMappingException;
+}

client/src/main/com/sinch/sdk/domains/numbers/adapters/NumbersService.java

@@ -18,6 +18,8 @@ public class NumbersService implements com.sinch.sdk.domains.numbers.NumbersServ
   private ActiveNumberService active;
   private AvailableRegionService regions;
   private CallbackConfigurationService callback;
+  private WebHooksService webhooks;
+
   private final Map<String, AuthManager> authManagers;
 
   public NumbersService(Configuration configuration, HttpClient httpClient) {
@@ -57,4 +59,12 @@ public CallbackConfigurationService callback() {
     }
     return this.callback;
   }
+
+  public WebHooksService webhooks() {
+
+    if (null == this.webhooks) {
+      this.webhooks = new WebHooksService();
+    }
+    return this.webhooks;
+  }
 }

client/src/main/com/sinch/sdk/domains/numbers/adapters/WebHooksService.java

@@ -0,0 +1,28 @@
+package com.sinch.sdk.domains.numbers.adapters;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.sinch.sdk.core.exceptions.ApiMappingException;
+import com.sinch.sdk.core.utils.databind.Mapper;
+import com.sinch.sdk.domains.numbers.adapters.converters.CallbackPayloadDtoConverter;
+import com.sinch.sdk.domains.numbers.models.dto.v1.CallbackPayloadDto;
+import com.sinch.sdk.domains.numbers.models.webhooks.EventNotification;
+
+public class WebHooksService implements com.sinch.sdk.domains.numbers.WebHooksService {
+
+  @Override
+  public EventNotification unserializeEventNotification(String jsonPayload)
+      throws ApiMappingException {
+
+    try {
+      CallbackPayloadDto dto =
+          Mapper.getInstance().readValue(jsonPayload, CallbackPayloadDto.class);
+      if (null != dto) {
+        return CallbackPayloadDtoConverter.convert(dto);
+      }
+      throw new ApiMappingException(jsonPayload, null);
+
+    } catch (JsonProcessingException e) {
+      throw new ApiMappingException(jsonPayload, e);
+    }
+  }
+}

client/src/main/com/sinch/sdk/domains/numbers/adapters/converters/ActiveNumberUpdateRequestParametersDtoConverter.java

@@ -15,9 +15,7 @@ public static ActiveNumberRequestDto convert(ActiveNumberUpdateRequestParameters
         .getVoiceConfiguration()
         .ifPresent(
             value -> dto.setVoiceConfiguration(VoiceConfigurationDtoConverter.convert(value)));
-    // TODO: OAS file do not yet contains callback field
-    // parameters.getCallback()
-    //           .ifPresent(value -> dto.setCallback.convert(value)));
+    parameters.getCallback().ifPresent(dto::setCallbackUrl);
     return dto;
   }
 }

client/src/main/com/sinch/sdk/domains/numbers/adapters/converters/CallbackPayloadDtoConverter.java

@@ -0,0 +1,41 @@
+package com.sinch.sdk.domains.numbers.adapters.converters;
+
+import com.sinch.sdk.domains.numbers.models.SmsErrorCode;
+import com.sinch.sdk.domains.numbers.models.dto.v1.CallbackPayloadDto;
+import com.sinch.sdk.domains.numbers.models.webhooks.EventNotification;
+import com.sinch.sdk.domains.numbers.models.webhooks.EventStatus;
+import com.sinch.sdk.domains.numbers.models.webhooks.EventType;
+import com.sinch.sdk.domains.numbers.models.webhooks.ResourceType;
+import java.time.Instant;
+import java.time.LocalDateTime;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeParseException;
+
+public class CallbackPayloadDtoConverter {
+
+  public static EventNotification convert(CallbackPayloadDto dto) {
+
+    String eventId = dto.getEventId();
+    // FIXME: Currently Numbers API return a string without timezone
+    // Workaround:
+    // 1. try to parse as ISO8601 (with timezone)
+    // 2. If failure: fallback to a local date time in UTC time zoe
+    Instant timestamp = null;
+    if (null != dto.getTimestamp()) {
+      try {
+        timestamp = Instant.parse(dto.getTimestamp());
+      } catch (DateTimeParseException e) {
+        timestamp = LocalDateTime.parse(dto.getTimestamp()).toInstant(ZoneOffset.UTC);
+      }
+    }
+    String projectId = dto.getProjectId();
+    String resourceId = dto.getResourceId();
+    ResourceType resourceType = ResourceType.from(dto.getResourceType());
+    EventType eventType = EventType.from(dto.getEventType());
+    EventStatus status = EventStatus.from(dto.getStatus());
+    SmsErrorCode failureCode = SmsErrorCode.from(dto.getFailureCode());
+
+    return new EventNotification(
+        eventId, timestamp, projectId, resourceId, resourceType, eventType, status, failureCode);
+  }
+}

client/src/main/com/sinch/sdk/domains/numbers/models/requests/ActiveNumberUpdateRequestParameters.java

@@ -16,11 +16,10 @@ public class ActiveNumberUpdateRequestParameters {
   private final String callback;
 
   /**
-   * @param displayName User supplied name for the phone number
-   * @param smsConfiguration The current SMS configuration for this number
-   * @param voiceConfiguration The current voice configuration for this number
-   * @param callback The callback URL to be called for a rented number's provisioning /
-   *     deprovisioning operations
+   * @param displayName see {@link #getDisplayName() getDisplayName getter}
+   * @param smsConfiguration see {@link #getSmsConfiguration() getSmsConfiguration getter}
+   * @param voiceConfiguration see {@link #getVoiceConfiguration() getVoiceConfiguration getter}
+   * @param callback see {@link #getCallback() getCallback getter}
    */
   public ActiveNumberUpdateRequestParameters(
       String displayName,
@@ -33,18 +32,31 @@ public ActiveNumberUpdateRequestParameters(
     this.callback = callback;
   }
 
+  /**
+   * @return User supplied name for the phone number
+   */
   public Optional<String> getDisplayName() {
     return Optional.ofNullable(displayName);
   }
 
+  /**
+   * @return The current SMS configuration for this number
+   */
   public Optional<ActiveNumberUpdateSMSConfigurationRequestParameters> getSmsConfiguration() {
     return Optional.ofNullable(smsConfiguration);
   }
 
+  /**
+   * @return The current voice configuration for this number
+   */
   public Optional<ActiveNumberUpdateVoiceConfigurationRequestParameters> getVoiceConfiguration() {
     return Optional.ofNullable(voiceConfiguration);
   }
 
+  /**
+   * @return The callback URL to be called for a rented number's provisioning / deprovisioning
+   *     operations ({@link com.sinch.sdk.domains.numbers.WebHooksService see WebHooksService})
+   */
   public Optional<String> getCallback() {
     return Optional.ofNullable(callback);
   }

client/src/main/com/sinch/sdk/domains/numbers/models/webhooks/EventNotification.java

@@ -0,0 +1,108 @@
+package com.sinch.sdk.domains.numbers.models.webhooks;
+
+import com.sinch.sdk.domains.numbers.models.SmsErrorCode;
+import java.time.Instant;
+
+/** A notification of an event sent to your configured callback URL. */
+public class EventNotification {
+
+  private final String eventId;
+  private final Instant timestamp;
+  private final String projectId;
+  private final String resourceId;
+  private final ResourceType resourceType;
+  private final EventType eventType;
+  private final EventStatus status;
+  private final SmsErrorCode failureCode;
+
+  /**
+   * @param eventId The ID of the event
+   * @param timestamp The date and time when the callback was created and added to the callbacks
+   *     queue
+   * @param projectId The ID of the project to which the event belongs
+   * @param resourceId The unique identifier of the resource, depending on the resource type. For
+   *     example, a phone number, a hosting order ID, or a brand ID.
+   * @param resourceType The type of the resource
+   * @param eventType The type of the event
+   * @param status The status of the event
+   * @param failureCode If the status is FAILED, a failure code will be provided. For numbers
+   *     provisioning to SMS platform, there won't be any extra failureCode, as the result is
+   *     binary. For campaign provisioning-related failures, refer to the list for the possible
+   *     values.
+   */
+  public EventNotification(
+      String eventId,
+      Instant timestamp,
+      String projectId,
+      String resourceId,
+      ResourceType resourceType,
+      EventType eventType,
+      EventStatus status,
+      SmsErrorCode failureCode) {
+    this.eventId = eventId;
+    this.timestamp = timestamp;
+    this.projectId = projectId;
+    this.resourceId = resourceId;
+    this.resourceType = resourceType;
+    this.eventType = eventType;
+    this.status = status;
+    this.failureCode = failureCode;
+  }
+
+  public String getEventId() {
+    return eventId;
+  }
+
+  public Instant getTimestamp() {
+    return timestamp;
+  }
+
+  public String getProjectId() {
+    return projectId;
+  }
+
+  public String getResourceId() {
+    return resourceId;
+  }
+
+  public ResourceType getResourceType() {
+    return resourceType;
+  }
+
+  public EventType getEventType() {
+    return eventType;
+  }
+
+  public EventStatus getStatus() {
+    return status;
+  }
+
+  public SmsErrorCode getFailureCode() {
+    return failureCode;
+  }
+
+  @Override
+  public String toString() {
+    return "EventNotification{"
+        + "eventId='"
+        + eventId
+        + '\''
+        + ", timestamp="
+        + timestamp
+        + ", projectId='"
+        + projectId
+        + '\''
+        + ", resourceId='"
+        + resourceId
+        + '\''
+        + ", resourceType="
+        + resourceType
+        + ", eventType="
+        + eventType
+        + ", status="
+        + status
+        + ", failureCode="
+        + failureCode
+        + '}';
+  }
+}

client/src/main/com/sinch/sdk/domains/numbers/models/webhooks/EventStatus.java

@@ -0,0 +1,38 @@
+package com.sinch.sdk.domains.numbers.models.webhooks;
+
+import com.sinch.sdk.core.utils.EnumDynamic;
+import com.sinch.sdk.core.utils.EnumSupportDynamic;
+import java.util.Arrays;
+import java.util.stream.Stream;
+
+public final class EventStatus extends EnumDynamic<String, EventStatus> {
+
+  /**
+   * @see <a
+   *     href="https://developers.sinch.com/docs/numbers/api-reference/numbers/tag/Callbacks/#tag/Callbacks/operation/ImportedNumberService_EventsCallback!path=status&t=request/">https://developers.sinch.com/docs/numbers/api-reference/numbers/tag/Callbacks/#tag/Callbacks/operation/ImportedNumberService_EventsCallback!path=status&amp;t=request/</a>
+   * @since 1.0
+   */
+  public static final EventStatus SUCCEEDED = new EventStatus("SUCCEEDED");
+
+  public static final EventStatus FAILED = new EventStatus("FAILED");
+
+  private static final EnumSupportDynamic<String, EventStatus> ENUM_SUPPORT =
+      new EnumSupportDynamic<>(
+          EventStatus.class, EventStatus::new, Arrays.asList(SUCCEEDED, FAILED));
+
+  EventStatus(String value) {
+    super(value);
+  }
+
+  public static Stream<EventStatus> values() {
+    return ENUM_SUPPORT.values();
+  }
+
+  public static EventStatus from(String value) {
+    return ENUM_SUPPORT.from(value);
+  }
+
+  public static String valueOf(EventStatus e) {
+    return ENUM_SUPPORT.valueOf(e);
+  }
+}