Add exception classes

Allow2Exception base with context map, ApiException with HTTP status,
TokenExpiredException and UnpairedException with userId tracking.

Co-Authored-By: claude-flow <ruv@ruv.net>

Author: Allow2 Dev

src/main/java/com/allow2/service/exceptions/Allow2Exception.java

@@ -0,0 +1,35 @@
+package com.allow2.service.exceptions;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Base exception for all Allow2 SDK errors.
+ */
+public class Allow2Exception extends RuntimeException {
+
+    private final Map<String, Object> context;
+
+    public Allow2Exception(String message, int code, Throwable cause, Map<String, Object> context) {
+        super(message, cause);
+        this.context = context != null ? Collections.unmodifiableMap(new HashMap<>(context)) : Collections.emptyMap();
+    }
+
+    public Allow2Exception(String message) {
+        this(message, 0, null, null);
+    }
+
+    public Allow2Exception(String message, Throwable cause) {
+        this(message, 0, cause, null);
+    }
+
+    /**
+     * Get the context map with additional error details.
+     *
+     * @return An unmodifiable context map.
+     */
+    public Map<String, Object> getContext() {
+        return context;
+    }
+}

src/main/java/com/allow2/service/exceptions/ApiException.java

@@ -0,0 +1,42 @@
+package com.allow2.service.exceptions;
+
+import org.json.JSONObject;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Thrown when an Allow2 API call fails with an unexpected error.
+ */
+public class ApiException extends Allow2Exception {
+
+    private final int httpStatusCode;
+    private final JSONObject responseBody;
+
+    public ApiException(String message, int httpStatusCode, JSONObject responseBody) {
+        this(message, httpStatusCode, responseBody, null);
+    }
+
+    public ApiException(String message, int httpStatusCode, JSONObject responseBody, Throwable cause) {
+        super(message, 0, cause, buildContext(httpStatusCode, responseBody));
+        this.httpStatusCode = httpStatusCode;
+        this.responseBody = responseBody;
+    }
+
+    public int getHttpStatusCode() {
+        return httpStatusCode;
+    }
+
+    public JSONObject getResponseBody() {
+        return responseBody;
+    }
+
+    private static Map<String, Object> buildContext(int httpStatusCode, JSONObject responseBody) {
+        Map<String, Object> ctx = new HashMap<>();
+        ctx.put("httpStatusCode", httpStatusCode);
+        if (responseBody != null) {
+            ctx.put("responseBody", responseBody.toString());
+        }
+        return ctx;
+    }
+}

src/main/java/com/allow2/service/exceptions/TokenExpiredException.java

@@ -0,0 +1,35 @@
+package com.allow2.service.exceptions;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Thrown when the OAuth2 token refresh fails and no valid token is available.
+ */
+public class TokenExpiredException extends Allow2Exception {
+
+    private final String userId;
+
+    public TokenExpiredException(String userId, String message) {
+        this(userId, message, null);
+    }
+
+    public TokenExpiredException(String userId, String message, Throwable cause) {
+        super(message, 0, cause, buildContext(userId));
+        this.userId = userId;
+    }
+
+    public TokenExpiredException(String userId) {
+        this(userId, "OAuth2 token refresh failed. Re-authorization required.", null);
+    }
+
+    public String getUserId() {
+        return userId;
+    }
+
+    private static Map<String, Object> buildContext(String userId) {
+        Map<String, Object> ctx = new HashMap<>();
+        ctx.put("userId", userId);
+        return ctx;
+    }
+}

src/main/java/com/allow2/service/exceptions/UnpairedException.java

@@ -0,0 +1,37 @@
+package com.allow2.service.exceptions;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Thrown when the service account is no longer linked (HTTP 401/403 from API).
+ *
+ * <p>The integration should redirect the user through OAuth2 re-pairing.</p>
+ */
+public class UnpairedException extends Allow2Exception {
+
+    private final String userId;
+
+    public UnpairedException(String userId, String message) {
+        this(userId, message, null);
+    }
+
+    public UnpairedException(String userId, String message, Throwable cause) {
+        super(message, 0, cause, buildContext(userId));
+        this.userId = userId;
+    }
+
+    public UnpairedException(String userId) {
+        this(userId, "Service account is no longer linked. Re-pairing required.", null);
+    }
+
+    public String getUserId() {
+        return userId;
+    }
+
+    private static Map<String, Object> buildContext(String userId) {
+        Map<String, Object> ctx = new HashMap<>();
+        ctx.put("userId", userId);
+        return ctx;
+    }
+}