Initial commit

src/main/java/ai/nomyo/errors/APIConnectionError.java

@@ -0,0 +1,41 @@
+package ai.nomyo.errors;
+
+/**
+ * Exception thrown when a network failure occurs during communication
+ * with the NOMYO API server.
+ *
+ * <p>This includes connection timeouts, DNS resolution failures,
+ * TLS handshake failures, and other network-level errors. Unlike
+ * {@link APIError}, this exception does not carry an HTTP status code.</p>
+ */
+public class APIConnectionError extends Exception {
+
+    /**
+     * Constructs an {@code APIConnectionError} with the specified detail message.
+     *
+     * @param message the detail message
+     */
+    public APIConnectionError(String message) {
+        super(message);
+    }
+
+    /**
+     * Constructs an {@code APIConnectionError} with the specified detail message
+     * and cause.
+     *
+     * @param message the detail message
+     * @param cause   the cause of this exception, or {@code null}
+     */
+    public APIConnectionError(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /**
+     * Constructs an {@code APIConnectionError} with the specified cause.
+     *
+     * @param cause the cause of this exception
+     */
+    public APIConnectionError(Throwable cause) {
+        super(cause);
+    }
+}

src/main/java/ai/nomyo/errors/APIError.java

@@ -0,0 +1,59 @@
+package ai.nomyo.errors;
+
+import java.util.Collections;
+import java.util.Map;
+
+/**
+ * Base exception for all NOMYO API errors.
+ *
+ * <p>All API error subclasses carry a {@code status_code} and optional
+ * {@code error_details} from the server response.</p>
+ */
+public class APIError extends Exception {
+
+    private final Integer statusCode;
+    private final Map<String, Object> errorDetails;
+
+    /**
+     * Constructs an {@code APIError} with the specified detail message,
+     * status code, and error details.
+     *
+     * @param message        the detail message
+     * @param statusCode     the HTTP status code, or {@code null} if not applicable
+     * @param errorDetails   additional error details from the server, or {@code null}
+     */
+    public APIError(String message, Integer statusCode, Map<String, Object> errorDetails) {
+        super(message);
+        this.statusCode = statusCode;
+        this.errorDetails = errorDetails != null
+                ? Collections.unmodifiableMap(errorDetails)
+                : Collections.emptyMap();
+    }
+
+    /**
+     * Constructs an {@code APIError} with the specified detail message.
+     *
+     * @param message the detail message
+     */
+    public APIError(String message) {
+        this(message, null, null);
+    }
+
+    /**
+     * Returns the HTTP status code associated with this error, or {@code null}.
+     *
+     * @return the status code, or {@code null}
+     */
+    public Integer getStatusCode() {
+        return statusCode;
+    }
+
+    /**
+     * Returns an unmodifiable map of additional error details from the server.
+     *
+     * @return the error details map (never {@code null})
+     */
+    public Map<String, Object> getErrorDetails() {
+        return errorDetails;
+    }
+}

src/main/java/ai/nomyo/errors/AuthenticationError.java

@@ -0,0 +1,41 @@
+package ai.nomyo.errors;
+
+import java.util.Map;
+
+/**
+ * Exception thrown when the API returns a 401 (Unauthorized) status.
+ */
+public class AuthenticationError extends APIError {
+
+    /**
+     * Constructs an {@code AuthenticationError} with the specified detail message,
+     * status code, and error details.
+     *
+     * @param message        the detail message
+     * @param statusCode     the HTTP status code (must be 401)
+     * @param errorDetails   additional error details from the server, or {@code null}
+     */
+    public AuthenticationError(String message, Integer statusCode, Map<String, Object> errorDetails) {
+        super(message, statusCode, errorDetails);
+    }
+
+    /**
+     * Constructs an {@code AuthenticationError} with the specified detail message.
+     *
+     * @param message the detail message
+     */
+    public AuthenticationError(String message) {
+        super(message, 401, null);
+    }
+
+    /**
+     * Constructs an {@code AuthenticationError} with the specified detail message
+     * and error details.
+     *
+     * @param message      the detail message
+     * @param errorDetails additional error details from the server, or {@code null}
+     */
+    public AuthenticationError(String message, Map<String, Object> errorDetails) {
+        super(message, 401, errorDetails);
+    }
+}

src/main/java/ai/nomyo/errors/ForbiddenError.java

@@ -0,0 +1,41 @@
+package ai.nomyo.errors;
+
+import java.util.Map;
+
+/**
+ * Exception thrown when the API returns a 403 (Forbidden) status.
+ */
+public class ForbiddenError extends APIError {
+
+    /**
+     * Constructs a {@code ForbiddenError} with the specified detail message,
+     * status code, and error details.
+     *
+     * @param message        the detail message
+     * @param statusCode     the HTTP status code (must be 403)
+     * @param errorDetails   additional error details from the server, or {@code null}
+     */
+    public ForbiddenError(String message, Integer statusCode, Map<String, Object> errorDetails) {
+        super(message, statusCode, errorDetails);
+    }
+
+    /**
+     * Constructs a {@code ForbiddenError} with the specified detail message.
+     *
+     * @param message the detail message
+     */
+    public ForbiddenError(String message) {
+        super(message, 403, null);
+    }
+
+    /**
+     * Constructs a {@code ForbiddenError} with the specified detail message
+     * and error details.
+     *
+     * @param message      the detail message
+     * @param errorDetails additional error details from the server, or {@code null}
+     */
+    public ForbiddenError(String message, Map<String, Object> errorDetails) {
+        super(message, 403, errorDetails);
+    }
+}

src/main/java/ai/nomyo/errors/InvalidRequestError.java

@@ -0,0 +1,41 @@
+package ai.nomyo.errors;
+
+import java.util.Map;
+
+/**
+ * Exception thrown when the API returns a 400 (Bad Request) status.
+ */
+public class InvalidRequestError extends APIError {
+
+    /**
+     * Constructs an {@code InvalidRequestError} with the specified detail message,
+     * status code, and error details.
+     *
+     * @param message        the detail message
+     * @param statusCode     the HTTP status code (must be 400)
+     * @param errorDetails   additional error details from the server, or {@code null}
+     */
+    public InvalidRequestError(String message, Integer statusCode, Map<String, Object> errorDetails) {
+        super(message, statusCode, errorDetails);
+    }
+
+    /**
+     * Constructs an {@code InvalidRequestError} with the specified detail message.
+     *
+     * @param message the detail message
+     */
+    public InvalidRequestError(String message) {
+        super(message, 400, null);
+    }
+
+    /**
+     * Constructs an {@code InvalidRequestError} with the specified detail message
+     * and error details.
+     *
+     * @param message      the detail message
+     * @param errorDetails additional error details from the server, or {@code null}
+     */
+    public InvalidRequestError(String message, Map<String, Object> errorDetails) {
+        super(message, 400, errorDetails);
+    }
+}

src/main/java/ai/nomyo/errors/RateLimitError.java

@@ -0,0 +1,41 @@
+package ai.nomyo.errors;
+
+import java.util.Map;
+
+/**
+ * Exception thrown when the API returns a 429 (Too Many Requests) status.
+ */
+public class RateLimitError extends APIError {
+
+    /**
+     * Constructs a {@code RateLimitError} with the specified detail message,
+     * status code, and error details.
+     *
+     * @param message        the detail message
+     * @param statusCode     the HTTP status code (must be 429)
+     * @param errorDetails   additional error details from the server, or {@code null}
+     */
+    public RateLimitError(String message, Integer statusCode, Map<String, Object> errorDetails) {
+        super(message, statusCode, errorDetails);
+    }
+
+    /**
+     * Constructs a {@code RateLimitError} with the specified detail message.
+     *
+     * @param message the detail message
+     */
+    public RateLimitError(String message) {
+        super(message, 429, null);
+    }
+
+    /**
+     * Constructs a {@code RateLimitError} with the specified detail message
+     * and error details.
+     *
+     * @param message      the detail message
+     * @param errorDetails additional error details from the server, or {@code null}
+     */
+    public RateLimitError(String message, Map<String, Object> errorDetails) {
+        super(message, 429, errorDetails);
+    }
+}

src/main/java/ai/nomyo/errors/SecurityError.java

@@ -0,0 +1,34 @@
+package ai.nomyo.errors;
+
+/**
+ * Exception thrown for cryptographic and key-related failures.
+ *
+ * <p>Unlike {@link APIError}, this exception carries no HTTP status code.
+ * It is used for issues such as invalid key sizes, encryption/decryption
+ * failures, and missing keys.</p>
+ *
+ * <p>Any decryption failure (except JSON parse errors) raises
+ * {@code SecurityError("Decryption failed: integrity check or authentication failed")}.</p>
+ */
+public class SecurityError extends Exception {
+
+    /**
+     * Constructs a {@code SecurityError} with the specified detail message.
+     *
+     * @param message the detail message
+     */
+    public SecurityError(String message) {
+        super(message);
+    }
+
+    /**
+     * Constructs a {@code SecurityError} with the specified detail message
+     * and cause.
+     *
+     * @param message the detail message
+     * @param cause   the underlying cause, or {@code null}
+     */
+    public SecurityError(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

src/main/java/ai/nomyo/errors/ServerError.java

@@ -0,0 +1,41 @@
+package ai.nomyo.errors;
+
+import java.util.Map;
+
+/**
+ * Exception thrown when the API returns a 500 (Internal Server Error) status.
+ */
+public class ServerError extends APIError {
+
+    /**
+     * Constructs a {@code ServerError} with the specified detail message,
+     * status code, and error details.
+     *
+     * @param message        the detail message
+     * @param statusCode     the HTTP status code (must be 500)
+     * @param errorDetails   additional error details from the server, or {@code null}
+     */
+    public ServerError(String message, Integer statusCode, Map<String, Object> errorDetails) {
+        super(message, statusCode, errorDetails);
+    }
+
+    /**
+     * Constructs a {@code ServerError} with the specified detail message.
+     *
+     * @param message the detail message
+     */
+    public ServerError(String message) {
+        super(message, 500, null);
+    }
+
+    /**
+     * Constructs a {@code ServerError} with the specified detail message
+     * and error details.
+     *
+     * @param message      the detail message
+     * @param errorDetails additional error details from the server, or {@code null}
+     */
+    public ServerError(String message, Map<String, Object> errorDetails) {
+        super(message, 500, errorDetails);
+    }
+}

src/main/java/ai/nomyo/errors/ServiceUnavailableError.java

@@ -0,0 +1,41 @@
+package ai.nomyo.errors;
+
+import java.util.Map;
+
+/**
+ * Exception thrown when the API returns a 503 (Service Unavailable) status.
+ */
+public class ServiceUnavailableError extends APIError {
+
+    /**
+     * Constructs a {@code ServiceUnavailableError} with the specified detail
+     * message, status code, and error details.
+     *
+     * @param message        the detail message
+     * @param statusCode     the HTTP status code (must be 503)
+     * @param errorDetails   additional error details from the server, or {@code null}
+     */
+    public ServiceUnavailableError(String message, Integer statusCode, Map<String, Object> errorDetails) {
+        super(message, statusCode, errorDetails);
+    }
+
+    /**
+     * Constructs a {@code ServiceUnavailableError} with the specified detail message.
+     *
+     * @param message the detail message
+     */
+    public ServiceUnavailableError(String message) {
+        super(message, 503, null);
+    }
+
+    /**
+     * Constructs a {@code ServiceUnavailableError} with the specified detail message
+     * and error details.
+     *
+     * @param message      the detail message
+     * @param errorDetails additional error details from the server, or {@code null}
+     */
+    public ServiceUnavailableError(String message, Map<String, Object> errorDetails) {
+        super(message, 503, errorDetails);
+    }
+}