fix: use smart defaults for Gateway Mode clientId (#67)

Replace requireCredentials() with getEffectiveClientId() that returns
"community" as default when clientId is not configured. This enables
zero-config usage for community/self-hosted deployments while still
supporting enterprise deployments with explicit credentials.

Gateway Mode methods (getPolicyApprovedContext, auditLLMCall) now work
without requiring credentials to be configured.

Author: saurabhjain1592

CHANGELOG.md

@@ -7,9 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [2.7.1] - 2026-01-25
 
+### Changed
+
+- **Gateway Mode smart defaults**: `getPolicyApprovedContext()` and `auditLLMCall()` now use `"community"` as default clientId when not configured, enabling zero-config usage for community/self-hosted deployments
+
 ### Fixed
 
-- **Gateway Mode credential enforcement**: `getPolicyApprovedContext()` and `auditLLMCall()` now require credentials (clientId), matching Go/Python SDK behavior for consistency across all SDKs
 - **PolicyCategory enum**: Added `PII_SINGAPORE("pii-singapore")` value for Singapore PII detection policies (NRIC, FIN, UEN patterns)
 - **proxyLLMCall clientId auto-injection**: Auto-populate `clientId` from config when not explicitly set in `ClientRequest`, matching Go/Python/TypeScript SDK behavior
 

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

@@ -294,22 +294,19 @@ public CompletableFuture<HealthStatus> orchestratorHealthCheckAsync() {
     public PolicyApprovalResult getPolicyApprovedContext(PolicyApprovalRequest request) {
         Objects.requireNonNull(request, "request cannot be null");
 
-        // Gateway Mode is an enterprise feature that requires credentials
-        requireCredentials("Gateway Mode (getPolicyApprovedContext)");
-
-        // Auto-populate clientId from config if not set in request (matches Go SDK behavior)
-        PolicyApprovalRequest effectiveRequest = request;
-        if ((request.getClientId() == null || request.getClientId().isEmpty())
-                && config.getClientId() != null && !config.getClientId().isEmpty()) {
-            Map<String, Object> ctx = request.getContext();
-            effectiveRequest = PolicyApprovalRequest.builder()
-                .userToken(request.getUserToken())
-                .query(request.getQuery())
-                .dataSources(request.getDataSources())
-                .context(ctx == null || ctx.isEmpty() ? null : ctx)
-                .clientId(config.getClientId())
-                .build();
-        }
+        // Use smart default for clientId - enables zero-config community mode
+        String effectiveClientId = (request.getClientId() != null && !request.getClientId().isEmpty())
+            ? request.getClientId()
+            : getEffectiveClientId();
+
+        Map<String, Object> ctx = request.getContext();
+        PolicyApprovalRequest effectiveRequest = PolicyApprovalRequest.builder()
+            .userToken(request.getUserToken())
+            .query(request.getQuery())
+            .dataSources(request.getDataSources())
+            .context(ctx == null || ctx.isEmpty() ? null : ctx)
+            .clientId(effectiveClientId)
+            .build();
 
         final PolicyApprovalRequest finalRequest = effectiveRequest;
         return retryExecutor.execute(() -> {
@@ -363,11 +360,32 @@ public CompletableFuture<PolicyApprovalResult> getPolicyApprovedContextAsync(Pol
     public AuditResult auditLLMCall(AuditOptions options) {
         Objects.requireNonNull(options, "options cannot be null");
 
-        // Gateway Mode is an enterprise feature that requires credentials
-        requireCredentials("Gateway Mode (auditLLMCall)");
+        // Use smart default for clientId - enables zero-config community mode
+        String effectiveClientId = (options.getClientId() != null && !options.getClientId().isEmpty())
+            ? options.getClientId()
+            : getEffectiveClientId();
+
+        // Create effective options with the smart default clientId
+        AuditOptions.Builder builder = AuditOptions.builder()
+            .contextId(options.getContextId())
+            .clientId(effectiveClientId)
+            .responseSummary(options.getResponseSummary())
+            .provider(options.getProvider())
+            .model(options.getModel())
+            .tokenUsage(options.getTokenUsage())
+            .metadata(options.getMetadata())
+            .success(options.getSuccess())
+            .errorMessage(options.getErrorMessage());
+
+        // Handle null latencyMs (builder takes primitive long)
+        if (options.getLatencyMs() != null) {
+            builder.latencyMs(options.getLatencyMs());
+        }
+
+        AuditOptions effectiveOptions = builder.build();
 
         return retryExecutor.execute(() -> {
-            Request httpRequest = buildRequest("POST", "/api/audit/llm-call", options);
+            Request httpRequest = buildRequest("POST", "/api/audit/llm-call", effectiveOptions);
             try (Response response = httpClient.newCall(httpRequest).execute()) {
                 return parseResponse(response, AuditResult.class);
             }
@@ -1952,16 +1970,17 @@ private void addAuthHeaders(Request.Builder builder) {
 
     /**
      * Requires credentials for enterprise features.
+     * Get the effective clientId, using smart default for community mode.
+     *
+     * <p>Returns the configured clientId if set, otherwise returns "community"
+     * as a smart default. This enables zero-config usage for community/self-hosted
+     * deployments while still supporting enterprise deployments with explicit credentials.
      *
-     * @param feature the feature name for error message
-     * @throws AuthenticationException if clientId is not configured
+     * @return the clientId to use in requests
      */
-    private void requireCredentials(String feature) {
-        if (!config.hasCredentials()) {
-            throw new AuthenticationException(
-                feature + " requires clientId. Set clientId in config (clientSecret is optional for community mode)."
-            );
-        }
+    private String getEffectiveClientId() {
+        String clientId = config.getClientId();
+        return (clientId != null && !clientId.isEmpty()) ? clientId : "community";
     }
 
     private void addTenantIdHeader(Request.Builder builder) {

src/main/java/com/getaxonflow/sdk/types/AuditOptions.java

@@ -78,7 +78,7 @@ public final class AuditOptions {
 
     private AuditOptions(Builder builder) {
         this.contextId = Objects.requireNonNull(builder.contextId, "contextId cannot be null");
-        this.clientId = Objects.requireNonNull(builder.clientId, "clientId cannot be null");
+        this.clientId = builder.clientId; // Optional - SDK will use smart default if null
         this.responseSummary = builder.responseSummary;
         this.provider = builder.provider;
         this.model = builder.model;

src/test/java/com/getaxonflow/sdk/types/MoreTypesTest.java

@@ -411,12 +411,14 @@ void shouldFailWhenContextIdIsNull() {
         }
 
         @Test
-        @DisplayName("should fail when clientId is null")
-        void shouldFailWhenClientIdIsNull() {
-            assertThatThrownBy(() -> AuditOptions.builder()
+        @DisplayName("should allow clientId to be null for smart defaults")
+        void shouldAllowClientIdToBeNull() {
+            // clientId can be null - SDK will use smart default "community"
+            AuditOptions options = AuditOptions.builder()
                 .contextId("ctx")
-                .build())
-                .isInstanceOf(NullPointerException.class);
+                .build();
+            assertThat(options.getContextId()).isEqualTo("ctx");
+            assertThat(options.getClientId()).isNull();
         }
 
         @Test