feat: add audit log read methods (searchAuditLogs, getAuditLogsByTenant)

* feat(audit): add audit log read methods

Add searchAuditLogs() and getAuditLogsByTenant() methods for reading
audit logs from the AxonFlow orchestrator.

New types:
- AuditSearchRequest: Builder-pattern request with filters
- AuditQueryOptions: Simple pagination options for tenant queries
- AuditLogEntry: Full audit log entry with all fields
- AuditSearchResponse: Response with entries, pagination, hasMore()

New methods:
- searchAuditLogs(request): POST /api/v1/audit/search
- searchAuditLogs(): Search with default limit (100)
- searchAuditLogsAsync(request): Async variant
- getAuditLogsByTenant(tenantId, options): GET /api/v1/audit/tenant/{id}
- getAuditLogsByTenant(tenantId): Query with default options
- getAuditLogsByTenantAsync(tenantId, options): Async variant

Features:
- Handles both array and wrapped response formats
- Limit capped at 1000 to prevent excessive queries
- URL encoding for tenant IDs with special characters
- Comprehensive test coverage (26 tests)

Part of Issue #878 - Add audit log read capabilities to SDK

* chore: add v1.13.0 changelog entry for audit read methods

Author: saurabhjain1592

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to the AxonFlow Java SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.13.0] - 2026-01-05
+
+### Added
+
+- **Audit Log Reading**: Added `searchAuditLogs()` for searching audit logs with filters (user email, client ID, time range, request type)
+- **Tenant Audit Logs**: Added `getAuditLogsByTenant()` for retrieving audit logs scoped to a specific tenant
+- **Audit Types**: Added `AuditLogEntry`, `AuditSearchRequest`, `AuditQueryOptions`, and `AuditSearchResponse` types
+
+---
+
 ## [1.12.0] - 2026-01-04
 
 ### Added

src/main/java/com/getaxonflow/sdk/AxonFlow.java

@@ -333,6 +333,141 @@ public CompletableFuture<AuditResult> auditLLMCallAsync(AuditOptions options) {
         return CompletableFuture.supplyAsync(() -> auditLLMCall(options), asyncExecutor);
     }
 
+    // ========================================================================
+    // Audit Log Read Methods
+    // ========================================================================
+
+    /**
+     * Searches audit logs with flexible filtering options.
+     *
+     * <p>Example usage:
+     * <pre>{@code
+     * AuditSearchResponse response = axonflow.searchAuditLogs(
+     *     AuditSearchRequest.builder()
+     *         .userEmail("analyst@company.com")
+     *         .startTime(Instant.now().minus(Duration.ofDays(7)))
+     *         .requestType("llm_chat")
+     *         .limit(100)
+     *         .build());
+     *
+     * for (AuditLogEntry entry : response.getEntries()) {
+     *     System.out.println(entry.getId() + ": " + entry.getQuerySummary());
+     * }
+     * }</pre>
+     *
+     * @param request the search request with optional filters
+     * @return the search response containing matching audit log entries
+     * @throws AxonFlowException if the search fails
+     */
+    public AuditSearchResponse searchAuditLogs(AuditSearchRequest request) {
+        return retryExecutor.execute(() -> {
+            AuditSearchRequest req = request != null ? request : AuditSearchRequest.builder().build();
+            Request httpRequest = buildOrchestratorRequest("POST", "/api/v1/audit/search", req);
+            try (Response response = httpClient.newCall(httpRequest).execute()) {
+                JsonNode node = parseResponseNode(response);
+
+                // Handle both array and wrapped response formats
+                if (node.isArray()) {
+                    List<AuditLogEntry> entries = objectMapper.convertValue(
+                        node, new TypeReference<List<AuditLogEntry>>() {});
+                    return AuditSearchResponse.fromArray(entries,
+                        req.getLimit() != null ? req.getLimit() : 100,
+                        req.getOffset() != null ? req.getOffset() : 0);
+                }
+
+                return objectMapper.treeToValue(node, AuditSearchResponse.class);
+            }
+        }, "searchAuditLogs");
+    }
+
+    /**
+     * Searches audit logs with default options (last 100 entries).
+     *
+     * @return the search response
+     */
+    public AuditSearchResponse searchAuditLogs() {
+        return searchAuditLogs(null);
+    }
+
+    /**
+     * Asynchronously searches audit logs.
+     *
+     * @param request the search request
+     * @return a future containing the search response
+     */
+    public CompletableFuture<AuditSearchResponse> searchAuditLogsAsync(AuditSearchRequest request) {
+        return CompletableFuture.supplyAsync(() -> searchAuditLogs(request), asyncExecutor);
+    }
+
+    /**
+     * Gets audit logs for a specific tenant.
+     *
+     * <p>Example usage:
+     * <pre>{@code
+     * AuditSearchResponse response = axonflow.getAuditLogsByTenant("tenant-abc",
+     *     AuditQueryOptions.builder()
+     *         .limit(100)
+     *         .offset(50)
+     *         .build());
+     *
+     * System.out.println("Total entries: " + response.getTotal());
+     * System.out.println("Has more: " + response.hasMore());
+     * }</pre>
+     *
+     * @param tenantId the tenant ID to query
+     * @param options optional pagination options
+     * @return the search response containing audit log entries for the tenant
+     * @throws IllegalArgumentException if tenantId is null or empty
+     * @throws AxonFlowException if the query fails
+     */
+    public AuditSearchResponse getAuditLogsByTenant(String tenantId, AuditQueryOptions options) {
+        if (tenantId == null || tenantId.isEmpty()) {
+            throw new IllegalArgumentException("tenantId is required");
+        }
+
+        return retryExecutor.execute(() -> {
+            AuditQueryOptions opts = options != null ? options : AuditQueryOptions.defaults();
+            String encodedTenantId = java.net.URLEncoder.encode(tenantId, "UTF-8");
+            String path = "/api/v1/audit/tenant/" + encodedTenantId +
+                "?limit=" + opts.getLimit() + "&offset=" + opts.getOffset();
+
+            Request httpRequest = buildOrchestratorRequest("GET", path, null);
+            try (Response response = httpClient.newCall(httpRequest).execute()) {
+                JsonNode node = parseResponseNode(response);
+
+                // Handle both array and wrapped response formats
+                if (node.isArray()) {
+                    List<AuditLogEntry> entries = objectMapper.convertValue(
+                        node, new TypeReference<List<AuditLogEntry>>() {});
+                    return AuditSearchResponse.fromArray(entries, opts.getLimit(), opts.getOffset());
+                }
+
+                return objectMapper.treeToValue(node, AuditSearchResponse.class);
+            }
+        }, "getAuditLogsByTenant");
+    }
+
+    /**
+     * Gets audit logs for a specific tenant with default options.
+     *
+     * @param tenantId the tenant ID to query
+     * @return the search response
+     */
+    public AuditSearchResponse getAuditLogsByTenant(String tenantId) {
+        return getAuditLogsByTenant(tenantId, null);
+    }
+
+    /**
+     * Asynchronously gets audit logs for a specific tenant.
+     *
+     * @param tenantId the tenant ID to query
+     * @param options optional pagination options
+     * @return a future containing the search response
+     */
+    public CompletableFuture<AuditSearchResponse> getAuditLogsByTenantAsync(String tenantId, AuditQueryOptions options) {
+        return CompletableFuture.supplyAsync(() -> getAuditLogsByTenant(tenantId, options), asyncExecutor);
+    }
+
     // ========================================================================
     // Proxy Mode - Query Execution
     // ========================================================================