Add core SDK modules

Port of PHP Service SDK core classes: Allow2Client facade with Builder
pattern, OAuth2Manager, PermissionChecker with caching, RequestManager,
VoiceCode (HMAC-SHA256), FeedbackManager, and HTTP client interface/impl
using java.net.http.HttpClient.

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

Author: Allow2 Dev

src/main/java/com/allow2/service/Allow2Client.java

@@ -0,0 +1,97 @@
+package com.allow2.service;
+
+import com.allow2.service.exceptions.ApiException;
+import org.json.JSONObject;
+
+import java.io.IOException;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.time.Duration;
+import java.util.Map;
+
+/**
+ * Default HTTP client implementation using {@link java.net.http.HttpClient}.
+ *
+ * <p>No external HTTP dependencies -- uses Java 11+ built-in HTTP client.</p>
+ */
+public final class Allow2HttpClient implements HttpClientInterface {
+
+    private static final int DEFAULT_TIMEOUT = 15;
+    private static final String DEFAULT_USER_AGENT = "Allow2-Java-SDK/2.0";
+
+    private final HttpClient client;
+    private final int timeout;
+    private final String userAgent;
+
+    /**
+     * Create an HTTP client with custom settings.
+     *
+     * @param timeout   Request timeout in seconds (default 15).
+     * @param userAgent User-Agent header value.
+     * @param client    Optional pre-built HttpClient instance.
+     */
+    public Allow2HttpClient(int timeout, String userAgent, HttpClient client) {
+        this.timeout = timeout;
+        this.userAgent = userAgent != null ? userAgent : DEFAULT_USER_AGENT;
+        this.client = client != null ? client : HttpClient.newBuilder()
+                .connectTimeout(Duration.ofSeconds(5))
+                .followRedirects(HttpClient.Redirect.NORMAL)
+                .build();
+    }
+
+    /**
+     * Create an HTTP client with default settings.
+     */
+    public Allow2HttpClient() {
+        this(DEFAULT_TIMEOUT, null, null);
+    }
+
+    @Override
+    public HttpResponse post(String url, Map<String, Object> data, Map<String, String> headers) {
+        String jsonBody = new JSONObject(data).toString();
+
+        HttpRequest.Builder builder = HttpRequest.newBuilder()
+                .uri(URI.create(url))
+                .timeout(Duration.ofSeconds(timeout))
+                .header("Content-Type", "application/json")
+                .header("Accept", "application/json")
+                .header("User-Agent", userAgent)
+                .POST(HttpRequest.BodyPublishers.ofString(jsonBody));
+
+        for (Map.Entry<String, String> entry : headers.entrySet()) {
+            builder.header(entry.getKey(), entry.getValue());
+        }
+
+        return execute(builder.build());
+    }
+
+    @Override
+    public HttpResponse get(String url, Map<String, String> headers) {
+        HttpRequest.Builder builder = HttpRequest.newBuilder()
+                .uri(URI.create(url))
+                .timeout(Duration.ofSeconds(timeout))
+                .header("Accept", "application/json")
+                .header("User-Agent", userAgent)
+                .GET();
+
+        for (Map.Entry<String, String> entry : headers.entrySet()) {
+            builder.header(entry.getKey(), entry.getValue());
+        }
+
+        return execute(builder.build());
+    }
+
+    private HttpResponse execute(HttpRequest request) {
+        try {
+            java.net.http.HttpResponse<String> response = client.send(
+                    request, java.net.http.HttpResponse.BodyHandlers.ofString());
+            return new HttpResponse(response.statusCode(), response.body());
+        } catch (IOException e) {
+            throw new ApiException("HTTP request failed: " + e.getMessage(), 0, null, e);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new ApiException("HTTP request interrupted: " + e.getMessage(), 0, null, e);
+        }
+    }
+}

src/main/java/com/allow2/service/Allow2HttpClient.java

@@ -0,0 +1,33 @@
+package com.allow2.service;
+
+/**
+ * Interface for caching permission check results.
+ *
+ * <p>Simple key-value cache with TTL support. Values are serialized strings.</p>
+ */
+public interface CacheInterface {
+
+    /**
+     * Retrieve a cached value by key.
+     *
+     * @param key Cache key.
+     * @return The cached value, or null if not found or expired.
+     */
+    String get(String key);
+
+    /**
+     * Store a value in cache.
+     *
+     * @param key   Cache key.
+     * @param value Value to cache.
+     * @param ttl   Time-to-live in seconds.
+     */
+    void set(String key, String value, int ttl);
+
+    /**
+     * Delete a cached value.
+     *
+     * @param key Cache key.
+     */
+    void delete(String key);
+}

src/main/java/com/allow2/service/CacheInterface.java

@@ -0,0 +1,171 @@
+package com.allow2.service;
+
+import com.allow2.service.exceptions.ApiException;
+import com.allow2.service.exceptions.UnpairedException;
+import com.allow2.service.models.FeedbackCategory;
+import org.json.JSONArray;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+import java.io.UnsupportedEncodingException;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.util.*;
+
+/**
+ * Manages feedback submission and discussion threads via the Allow2 API.
+ *
+ * <p>Feedback allows users to report issues, request features, or communicate
+ * with the Allow2 Parental Freedom support team.</p>
+ */
+public final class FeedbackManager {
+
+    private final HttpClientInterface httpClient;
+    private final String apiHost;
+
+    public FeedbackManager(HttpClientInterface httpClient, String apiHost) {
+        this.httpClient = httpClient;
+        this.apiHost = apiHost;
+    }
+
+    /**
+     * Submit new feedback.
+     *
+     * @param accessToken Valid OAuth2 access token.
+     * @param userId      The integrating application's user ID.
+     * @param category    The feedback category.
+     * @param message     The feedback message.
+     * @return The discussion ID for the created feedback thread.
+     * @throws UnpairedException If the API returns 401/403.
+     * @throws ApiException      On other API failures.
+     */
+    public String submit(String accessToken, String userId, FeedbackCategory category, String message) {
+        Map<String, Object> data = new LinkedHashMap<>();
+        data.put("access_token", accessToken);
+        data.put("category", category.getValue());
+        data.put("message", message);
+
+        HttpResponse response = httpClient.post(apiHost + "/feedback/submit", data);
+
+        if (response.isUnauthorized()) {
+            throw new UnpairedException(userId);
+        }
+
+        if (!response.isSuccess()) {
+            JSONObject body = safeJson(response);
+            throw new ApiException(
+                    "Failed to submit feedback: HTTP " + response.getStatusCode(),
+                    response.getStatusCode(),
+                    body
+            );
+        }
+
+        JSONObject responseData = response.json();
+        if (responseData.has("discussionId")) {
+            return responseData.getString("discussionId");
+        }
+        if (responseData.has("feedbackId")) {
+            return responseData.getString("feedbackId");
+        }
+        if (responseData.has("id")) {
+            return String.valueOf(responseData.get("id"));
+        }
+        return "";
+    }
+
+    /**
+     * Load all feedback discussions for the authenticated user.
+     *
+     * @param accessToken Valid OAuth2 access token.
+     * @param userId      The integrating application's user ID.
+     * @return List of feedback discussion threads as maps.
+     * @throws UnpairedException If the API returns 401/403.
+     * @throws ApiException      On other API failures.
+     */
+    public List<Map<String, Object>> load(String accessToken, String userId) {
+        Map<String, String> headers = new LinkedHashMap<>();
+        headers.put("Authorization", "Bearer " + accessToken);
+
+        HttpResponse response = httpClient.get(apiHost + "/feedback/load", headers);
+
+        if (response.isUnauthorized()) {
+            throw new UnpairedException(userId);
+        }
+
+        if (!response.isSuccess()) {
+            JSONObject body = safeJson(response);
+            throw new ApiException(
+                    "Failed to load feedback: HTTP " + response.getStatusCode(),
+                    response.getStatusCode(),
+                    body
+            );
+        }
+
+        JSONObject data = response.json();
+        JSONArray discussions;
+        if (data.has("discussions")) {
+            discussions = data.getJSONArray("discussions");
+        } else if (data.has("feedback")) {
+            discussions = data.getJSONArray("feedback");
+        } else {
+            return Collections.emptyList();
+        }
+
+        List<Map<String, Object>> result = new ArrayList<>();
+        for (int i = 0; i < discussions.length(); i++) {
+            JSONObject item = discussions.getJSONObject(i);
+            result.add(item.toMap());
+        }
+        return result;
+    }
+
+    /**
+     * Reply to an existing feedback discussion thread.
+     *
+     * @param accessToken  Valid OAuth2 access token.
+     * @param userId       The integrating application's user ID.
+     * @param discussionId The discussion thread ID to reply to.
+     * @param message      The reply message.
+     * @throws UnpairedException If the API returns 401/403.
+     * @throws ApiException      On other API failures.
+     */
+    public void reply(String accessToken, String userId, String discussionId, String message) {
+        Map<String, Object> data = new LinkedHashMap<>();
+        data.put("access_token", accessToken);
+        data.put("message", message);
+
+        HttpResponse response = httpClient.post(
+                apiHost + "/feedback/" + urlEncode(discussionId) + "/reply",
+                data
+        );
+
+        if (response.isUnauthorized()) {
+            throw new UnpairedException(userId);
+        }
+
+        if (!response.isSuccess()) {
+            JSONObject body = safeJson(response);
+            throw new ApiException(
+                    "Failed to reply to feedback: HTTP " + response.getStatusCode(),
+                    response.getStatusCode(),
+                    body
+            );
+        }
+    }
+
+    private static String urlEncode(String value) {
+        try {
+            return URLEncoder.encode(value, StandardCharsets.UTF_8.name());
+        } catch (UnsupportedEncodingException e) {
+            throw new RuntimeException(e);
+        }
+    }
+
+    private static JSONObject safeJson(HttpResponse response) {
+        try {
+            return response.json();
+        } catch (JSONException e) {
+            return null;
+        }
+    }
+}

src/main/java/com/allow2/service/FeedbackManager.java

@@ -0,0 +1,52 @@
+package com.allow2.service;
+
+import java.util.Map;
+
+/**
+ * HTTP client interface for Allow2 API calls.
+ *
+ * <p>Implementations must handle JSON encoding/decoding and return
+ * an {@link HttpResponse} value object.</p>
+ */
+public interface HttpClientInterface {
+
+    /**
+     * Send a POST request.
+     *
+     * @param url     Full URL to send to.
+     * @param data    Body data (will be JSON-encoded by the implementation).
+     * @param headers Additional headers.
+     * @return The HTTP response.
+     */
+    HttpResponse post(String url, Map<String, Object> data, Map<String, String> headers);
+
+    /**
+     * Send a POST request with no extra headers.
+     *
+     * @param url  Full URL to send to.
+     * @param data Body data (will be JSON-encoded by the implementation).
+     * @return The HTTP response.
+     */
+    default HttpResponse post(String url, Map<String, Object> data) {
+        return post(url, data, Map.of());
+    }
+
+    /**
+     * Send a GET request.
+     *
+     * @param url     Full URL to send to.
+     * @param headers Additional headers.
+     * @return The HTTP response.
+     */
+    HttpResponse get(String url, Map<String, String> headers);
+
+    /**
+     * Send a GET request with no extra headers.
+     *
+     * @param url Full URL to send to.
+     * @return The HTTP response.
+     */
+    default HttpResponse get(String url) {
+        return get(url, Map.of());
+    }
+}