feat: javadoc

Author: QuentinTournier40

src/main/java/dev/resms/ReSMS.java

@@ -7,30 +7,74 @@
 import dev.resms.service.SmsService;
 import lombok.NonNull;
 
-/** ReSMS Java SDK - Client principal */
+/**
+ * This class serves as the primary entry point for the ReSMS Java SDK, providing a simple interface
+ * for sending SMS messages through the ReSMS API.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * // Initialize with API key
+ * ReSMS client = new ReSMS("your-api-key");
+ *
+ * // Send a simple SMS
+ * try {
+ *     SendSmsResponse response = client.sendSms("+1234567890", "Hello from ReSMS!");
+ *     System.out.println("Message sent with ID: " + response.getData().getMessageId());
+ * } catch (ReSMSException e) {
+ *     System.err.println("Failed to send SMS: " + e.getMessage());
+ * }
+ * }</pre>
+ *
+ * @since 1.0.0
+ * @see dev.resms.service.SmsService
+ * @see dev.resms.config.ReSMSConfig
+ */
 public class ReSMS {
+  /** The SMS service used to send messages */
   private final SmsService smsService;
 
   /**
-   * Creates a new ReSMS client with a default timeout of 10 seconds
+   * Creates a new ReSMS client with the specified API key.
    *
-   * @param apiKey API key for authentication
+   * <p>This constructor uses default configuration settings with the provided API key.
+   *
+   * @param apiKey The API key for authentication with the ReSMS service. Must not be {@code null}
+   *     or blank.
+   * @throws IllegalArgumentException if the API key is blank
+   * @see ReSMSConfig
    */
   public ReSMS(@NonNull String apiKey) {
     this(new ReSMSConfig(apiKey));
   }
 
+  /**
+   * Creates a new ReSMS client with the specified configuration.
+   *
+   * <p>This constructor allows for more customized configuration options.
+   *
+   * @param config The configuration object containing API key and other settings. Must not be
+   *     {@code null}.
+   * @see ReSMSConfig
+   */
   public ReSMS(@NonNull ReSMSConfig config) {
     this.smsService = new SmsService(config);
   }
 
   /**
-   * Sends an SMS message - Main method
+   * Sends an SMS message to the specified phone number.
+   *
+   * <p>This is a convenience method that creates a {@link SendSmsRequest} object and delegates to
+   * {@link #sendSms(SendSmsRequest)}.
    *
-   * @param to Phone number to send the message to
-   * @param message Message content
-   * @return SendSmsResponse containing the message ID and status
-   * @throws ReSMSException if fails
+   * @param to The phone number to send the message to, in E.164 format (e.g., "+1234567890"). Must
+   *     not be {@code null}.
+   * @param message The content of the SMS message. Must not be {@code null}.
+   * @return A {@link SendSmsResponse} containing the message ID and status information.
+   * @throws ReSMSException if the message cannot be sent due to API errors, network issues,
+   *     validation failures, or insufficient quota.
+   * @see SendSmsRequest
+   * @see SendSmsResponse
    */
   public SendSmsResponse sendSms(@NonNull String to, @NonNull String message)
       throws ReSMSException {
@@ -39,11 +83,18 @@ public SendSmsResponse sendSms(@NonNull String to, @NonNull String message)
   }
 
   /**
-   * Sends an SMS message using request object
+   * Sends an SMS message using a request object.
+   *
+   * <p>This method provides more control over the SMS sending process by accepting a pre-configured
+   * request object.
    *
-   * @param request SendSmsRequest object
-   * @return SendSmsResponse containing the message ID and status
-   * @throws ReSMSException if fails
+   * @param request The {@link SendSmsRequest} object containing the recipient phone number, message
+   *     content, and optional parameters. Must not be {@code null}.
+   * @return A {@link SendSmsResponse} containing the message ID and status information.
+   * @throws ReSMSException if the message cannot be sent due to API errors, network issues,
+   *     validation failures, or insufficient quota.
+   * @see SendSmsRequest
+   * @see SendSmsResponse
    */
   public SendSmsResponse sendSms(@NonNull SendSmsRequest request) throws ReSMSException {
     return smsService.sendSms(request);

src/main/java/dev/resms/api/ReSMSApiClient.java

@@ -19,15 +19,50 @@
 import java.net.http.HttpResponse;
 import org.apache.hc.core5.http.HttpStatus;
 
+/**
+ * This class handles the low-level HTTP communication with the ReSMS API service. It is responsible
+ * for serializing requests, making HTTP calls, deserializing responses, and translating API errors
+ * into appropriate exception types.
+ *
+ * <p>This class is typically not used directly by end users, but rather through the {@link
+ * dev.resms.service.SmsService} and {@link dev.resms.ReSMS} classes.
+ *
+ * <p>The client uses Java's {@link HttpClient} for HTTP communication and <a
+ * href="https://github.com/square/moshi">Moshi</a> for JSON serialization/deserialization.
+ *
+ * @since 1.0.0
+ * @see dev.resms.service.SmsService
+ * @see dev.resms.ReSMS
+ * @see dev.resms.config.ReSMSConfig
+ */
 public class ReSMSApiClient {
+  /** The API endpoint path for sending SMS messages. */
   private static final String SEND_SMS_PATH = "sms/send";
 
+  /** The configuration object containing API key and other settings. */
   private final ReSMSConfig config;
+
+  /** The HTTP client used for making API requests. */
   private final HttpClient httpClient;
+
+  /** JSON adapter for serializing {@link SendSmsRequest} objects. */
   private final JsonAdapter<SendSmsRequest> requestAdapter;
+
+  /** JSON adapter for deserializing {@link SendSmsResponse} objects. */
   private final JsonAdapter<SendSmsResponse> responseAdapter;
+
+  /** JSON adapter for deserializing {@link ErrorResponse} objects. */
   private final JsonAdapter<ErrorResponse> errorResponseAdapter;
 
+  /**
+   * Creates a new API client with the specified configuration.
+   *
+   * <p>Initializes the HTTP client and JSON adapters for serialization/deserialization.
+   *
+   * @param config The configuration object containing API key and other settings. Must not be
+   *     {@code null}.
+   * @see ReSMSConfig
+   */
   public ReSMSApiClient(ReSMSConfig config) {
     this.config = config;
     this.httpClient = HttpClient.newBuilder().build();
@@ -39,6 +74,30 @@ public ReSMSApiClient(ReSMSConfig config) {
     this.errorResponseAdapter = moshi.adapter(ErrorResponse.class);
   }
 
+  /**
+   * Sends an SMS message by making an HTTP request to the ReSMS API.
+   *
+   * <p>This method performs the following steps:
+   *
+   * <ol>
+   *   <li>Serializes the request object to JSON
+   *   <li>Creates an HTTP request with appropriate headers
+   *   <li>Sends the HTTP request to the API
+   *   <li>Processes the HTTP response
+   *   <li>Deserializes the response JSON
+   *   <li>Returns the response object or throws an appropriate exception
+   * </ol>
+   *
+   * @param requestBody The {@link SendSmsRequest} object containing the recipient phone number,
+   *     message content, and optional parameters. Must not be {@code null}.
+   * @return A {@link SendSmsResponse} containing the message ID and status information.
+   * @throws ReSMSException if the message cannot be sent due to API errors, network issues, or
+   *     other failures. The specific subclass of {@link ReSMSException} depends on the error type
+   *     returned by the API.
+   * @see SendSmsRequest
+   * @see SendSmsResponse
+   * @see ReSMSException
+   */
   public SendSmsResponse sendSms(SendSmsRequest requestBody) throws ReSMSException {
     String jsonBody = requestAdapter.toJson(requestBody);
 

src/main/java/dev/resms/config/ReSMSConfig.java

@@ -3,13 +3,51 @@
 import lombok.Getter;
 import lombok.NonNull;
 
-/** Configuration class for ReSMS SDK */
+/**
+ * This class holds configuration settings for the ReSMS SDK, including the API key required for
+ * authentication with the ReSMS API service.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * // Create a basic configuration with just the API key
+ * ReSMSConfig config = new ReSMSConfig("your-api-key");
+ *
+ * // Use the configuration to initialize the ReSMS client
+ * ReSMS client = new ReSMS(config);
+ * }</pre>
+ *
+ * <p>The configuration object is immutable once created.
+ *
+ * @since 1.0.0
+ * @see dev.resms.ReSMS
+ */
 @Getter
 public class ReSMSConfig {
+  /**
+   * The base URL for the ReSMS API.
+   *
+   * <p>This constant defines the endpoint for all API requests made by the SDK.
+   */
   public static final String BASE_URL = "https://api.resms.dev/";
 
+  /**
+   * The API key used for authentication with the ReSMS service.
+   *
+   * <p>This field is final and can only be set during object construction.
+   */
   private final String apiKey;
 
+  /**
+   * Creates a new configuration object with the specified API key.
+   *
+   * <p>The API key is validated to ensure it is not blank. Leading and trailing whitespace is
+   * automatically trimmed.
+   *
+   * @param apiKey The API key for authentication with the ReSMS service. Must not be {@code null}
+   *     or blank.
+   * @throws IllegalArgumentException if the API key is blank or {@code null}
+   */
   public ReSMSConfig(@NonNull String apiKey) {
     if (apiKey.isBlank()) {
       throw new IllegalArgumentException("API key cannot be blank");

src/main/java/dev/resms/exception/ReSMSException.java

@@ -1,10 +1,59 @@
 package dev.resms.exception;
 
+/**
+ * This is the base exception class for all exceptions thrown by the ReSMS SDK. It extends {@link
+ * RuntimeException}, making all ReSMS exceptions unchecked.
+ *
+ * <p>This class serves as a parent for more specific exception types that provide detailed
+ * information about specific error conditions. When catching exceptions from the ReSMS SDK, you can
+ * either catch this base exception type or specific subclasses for more granular error handling.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * try {
+ *     ReSMS client = new ReSMS("your-api-key");
+ *     client.sendSms("+1234567890", "Hello from ReSMS!");
+ * } catch (InvalidApiKeyException e) {
+ *     // Handle invalid API key specifically
+ *     System.err.println("Your API key is invalid: " + e.getMessage());
+ * } catch (ReSMSException e) {
+ *     // Handle any other ReSMS exception
+ *     System.err.println("Failed to send SMS: " + e.getMessage());
+ * }
+ * }</pre>
+ *
+ * @since 1.0.0
+ * @see java.lang.RuntimeException
+ * @see dev.resms.exception.user.InvalidApiKeyException
+ * @see dev.resms.exception.sms.InsufficientSmsQuotaException
+ */
 public class ReSMSException extends RuntimeException {
+  /**
+   * Constructs a new ReSMS exception with the specified detail message.
+   *
+   * <p>The cause is not initialized, and may subsequently be initialized by a call to {@link
+   * #initCause}.
+   *
+   * @param message The detail message. The detail message is saved for later retrieval by the
+   *     {@link #getMessage()} method.
+   */
   public ReSMSException(String message) {
     super(message);
   }
 
+  /**
+   * Constructs a new ReSMS exception with the specified detail message and cause.
+   *
+   * <p>Note that the detail message associated with {@code cause} is <i>not</i> automatically
+   * incorporated in this exception's detail message.
+   *
+   * @param message The detail message (which is saved for later retrieval by the {@link
+   *     #getMessage()} method).
+   * @param cause The cause (which is saved for later retrieval by the {@link #getCause()} method).
+   *     (A {@code null} value is permitted, and indicates that the cause is nonexistent or
+   *     unknown.)
+   */
   public ReSMSException(String message, Throwable cause) {
     super(message, cause);
   }

src/main/java/dev/resms/exception/senderid/NoDefaultSenderIdException.java

@@ -2,7 +2,44 @@
 
 import dev.resms.exception.ReSMSException;
 
+/**
+ * This exception is thrown when an SMS message is being sent without specifying a sender ID, and
+ * there is no default sender ID configured for the account. A sender ID is required for sending SMS
+ * messages as it identifies the sender to the recipient.
+ *
+ * <p>This exception typically occurs when:
+ *
+ * <ul>
+ *   <li>The account has not configured any sender IDs
+ *   <li>The account has multiple sender IDs but none is set as the default
+ *   <li>The default sender ID has been removed or deactivated
+ * </ul>
+ *
+ * <p>Example handling:
+ *
+ * <pre>{@code
+ * try {
+ *     // Attempting to send SMS without specifying a sender ID
+ *     ReSMS client = new ReSMS("your-api-key");
+ *     client.sendSms("+1234567890", "Hello from ReSMS!");
+ * } catch (NoDefaultSenderIdException e) {
+ *     System.err.println("No default sender ID: " + e.getMessage());
+ *     System.err.println("Please configure a default sender ID in your ReSMS dashboard or specify a sender ID in your request.");
+ * }
+ * }</pre>
+ *
+ * @since 1.0.0
+ * @see dev.resms.exception.ReSMSException
+ * @see dev.resms.exception.senderid.SenderIdNotFoundException
+ */
 public class NoDefaultSenderIdException extends ReSMSException {
+  /**
+   * Constructs a new NoDefaultSenderIdException with the specified detail message.
+   *
+   * @param message The detail message explaining the issue with the default sender ID. This message
+   *     typically includes guidance on how to configure a default sender ID or how to specify a
+   *     sender ID in the request.
+   */
   public NoDefaultSenderIdException(String message) {
     super(message);
   }

src/main/java/dev/resms/exception/senderid/SenderIdNotFoundException.java

@@ -2,7 +2,48 @@
 
 import dev.resms.exception.ReSMSException;
 
+/**
+ * This exception is thrown when an SMS message is being sent with a specified sender ID that does
+ * not exist or is not associated with the account. A valid sender ID is required for sending SMS
+ * messages as it identifies the sender to the recipient.
+ *
+ * <p>This exception typically occurs when:
+ *
+ * <ul>
+ *   <li>The specified sender ID has never been registered with the account
+ *   <li>The sender ID has been deleted or deactivated
+ *   <li>There is a typo or case mismatch in the sender ID
+ *   <li>The sender ID belongs to a different account
+ * </ul>
+ *
+ * <p>Example handling:
+ *
+ * <pre>{@code
+ * try {
+ *     // Attempting to send SMS with a non-existent sender ID
+ *     SendSmsRequest request = new SendSmsRequest("+1234567890", "Hello from ReSMS!");
+ *     request.setSenderId("NonExistentID");
+ *
+ *     ReSMS client = new ReSMS("your-api-key");
+ *     client.sendSms(request);
+ * } catch (SenderIdNotFoundException e) {
+ *     System.err.println("Sender ID not found: " + e.getMessage());
+ *     System.err.println("Please verify the sender ID or use a different one.");
+ * }
+ * }</pre>
+ *
+ * @since 1.0.0
+ * @see dev.resms.exception.ReSMSException
+ * @see dev.resms.exception.senderid.NoDefaultSenderIdException
+ */
 public class SenderIdNotFoundException extends ReSMSException {
+  /**
+   * Constructs a new SenderIdNotFoundException with the specified detail message.
+   *
+   * @param message The detail message explaining the issue with the sender ID. This message
+   *     typically includes information about which sender ID was not found and may suggest
+   *     available sender IDs for the account.
+   */
   public SenderIdNotFoundException(String message) {
     super(message);
   }