Devesh/sk 2814 java public interface cleanup

README.md

@@ -50,6 +50,9 @@ The Skyflow Java SDK is designed to help with integrating Skyflow into a Java ba
   - [Generate scoped bearer tokens](#generate-scoped-bearer-tokens)
   - [Generate signed data tokens](#generate-signed-data-tokens)
   - [Bearer token expiry edge case](#bearer-token-expiry-edge-case)
+- [Error Handling](#error-handling)
+  - [Catching SkyflowException](#catching-skyflowexception)
+  - [SkyflowException properties](#skyflowexception-properties)
 - [Logging](#logging)
 - [Reporting a Vulnerability](#reporting-a-vulnerability)
 
@@ -2786,6 +2789,48 @@ public class DetokenizeExample {
 }
 ```
 
+# Error Handling
+
+The SDK uses `SkyflowException` for all errors — both client-side validation errors and server-side API errors.
+
+## Catching SkyflowException
+
+Wrap SDK calls in a `try/catch` block and catch `SkyflowException` to handle Skyflow-specific errors separately from unexpected exceptions:
+
+```java
+import com.skyflow.errors.SkyflowException;
+
+try {
+    InsertResponse response = skyflowClient.vault().insert(insertRequest);
+} catch (SkyflowException e) {
+    System.err.println("Skyflow error:");
+    System.err.println("  HTTP code : " + e.getHttpCode());
+    System.err.println("  Message   : " + e.getMessage());
+    System.err.println("  Request ID: " + e.getRequestId());
+    System.err.println("  Details   : " + e.getDetails());
+} catch (Exception e) {
+    System.err.println("Unexpected error: " + e.getMessage());
+}
+```
+
+## SkyflowException properties
+
+| Property | Method | Description |
+|---|---|---|
+| HTTP status code | `getHttpCode()` | Integer status code (e.g. `400`, `404`, `500`). |
+| Message | `getMessage()` | Human-readable description of the error. |
+| HTTP status string | `getHttpStatus()` | Status string from the server (e.g. `"BAD_REQUEST"`). |
+| gRPC code | `getGrpcCode()` | gRPC status code from the server. |
+| Request ID | `getRequestId()` | The `x-request-id` header — useful for support escalations. |
+| Details | `getDetails()` | `JsonArray` of additional error context from the server. Empty array for validation errors, `null` if the server response omitted the field. |
+
+**Validation errors** (missing table name, empty token list, etc.) are thrown before any network call:
+- `httpCode` is always `400`
+- `requestId` and `grpcCode` are `null`
+- `details` is an empty array
+
+**API errors** are returned by the Skyflow server and have all fields populated from the response body and headers.
+
 # Logging
 
 The SDK provides logging with Java's built-in logging library. By default, the SDK's logging level is set to `LogLevel.ERROR`. This can be changed using the `setLogLevel(logLevel)` method, as shown below:

docs/migrate_to_v2.md

@@ -249,4 +249,35 @@ Response maps now return `skyflowId` (camelCase). The legacy `skyflow_id` key is
 
 ---
 
+## Update request data key (v2.1+)
+
+When calling `update()`, use `skyflowId` (camelCase) as the key in the data map to identify the record. Using `skyflow_id` still works but emits a deprecation warning. If both keys are present, `skyflowId` takes precedence.
+
+```java
+HashMap<String, Object> data = new HashMap<>();
+data.put("skyflowId", "<SKYFLOW_ID>");   // preferred
+data.put("card_number", "<NEW_VALUE>");
+
+UpdateRequest request = UpdateRequest.builder()
+    .table("<TABLE_NAME>")
+    .data(data)
+    .returnTokens(true)
+    .build();
+
+skyflowClient.vault().update(request);
+```
+
+---
+
+## Method renames (v2.1+)
+
+The following instance methods have been renamed for consistency. The old names still work but emit deprecation warnings.
+
+| Deprecated | Preferred |
+|---|---|
+| `skyflowClient.updateLogLevel(logLevel)` | `skyflowClient.setLogLevel(logLevel)` |
+| `TokenMode.getBYOT()` | `TokenMode.getByot()` |
+
+---
+
 For the full list of changes see [CHANGELOG.md](../CHANGELOG.md).

samples/src/main/java/com/example/vault/UpdateExample.java

@@ -46,7 +46,7 @@ public static void main(String[] args) throws SkyflowException {
         // Step 5: Update records with TokenMode enabled
         try {
             HashMap<String, Object> data1 = new HashMap<>();
-            data1.put("skyflow_id", "<YOUR_SKYFLOW_ID>"); // Replace with the Skyflow ID of the record
+            data1.put("skyflowId", "<YOUR_SKYFLOW_ID>"); // Replace with the Skyflow ID of the record
             data1.put("<COLUMN_NAME_1>", "<COLUMN_VALUE_1>"); // Replace with column name and value to update
             data1.put("<COLUMN_NAME_2>", "<COLUMN_VALUE_2>"); // Replace with another column name and value
 
@@ -71,7 +71,7 @@ public static void main(String[] args) throws SkyflowException {
         // Step 6: Update records with TokenMode disabled
         try {
             HashMap<String, Object> data2 = new HashMap<>();
-            data2.put("skyflow_id", "<YOUR_SKYFLOW_ID>"); // Replace with the Skyflow ID of the record
+            data2.put("skyflowId", "<YOUR_SKYFLOW_ID>"); // Replace with the Skyflow ID of the record
             data2.put("<COLUMN_NAME_1>", "<COLUMN_VALUE_1>"); // Replace with column name and value to update
             data2.put("<COLUMN_NAME_2>", "<COLUMN_VALUE_2>"); // Replace with another column name and value
 

samples/src/main/java/com/example/vault/deprecated/UpdateExample.java

@@ -0,0 +1,94 @@
+package com.example.vault.deprecated;
+
+import com.skyflow.Skyflow;
+import com.skyflow.config.Credentials;
+import com.skyflow.config.VaultConfig;
+import com.skyflow.enums.Env;
+import com.skyflow.enums.LogLevel;
+import com.skyflow.enums.TokenMode;
+import com.skyflow.errors.SkyflowException;
+import com.skyflow.vault.data.UpdateRequest;
+import com.skyflow.vault.data.UpdateResponse;
+
+import java.util.HashMap;
+
+/**
+ * @deprecated Pre-v2.1 pattern. The "skyflow_id" key in the data map is deprecated.
+ * Use "skyflowId" instead (see {@link com.example.vault.UpdateExample}).
+ *
+ * This example is retained for reference during the deprecation window.
+ * "skyflow_id" still works but emits a runtime warning and will be removed in a future release.
+ */
+@Deprecated
+public class UpdateExample {
+    public static void main(String[] args) throws SkyflowException {
+        // Step 1: Set up credentials for the first vault configuration
+        Credentials credentials = new Credentials();
+        credentials.setApiKey("<YOUR_API_KEY>"); // Replace with the actual API key
+
+        // Step 2: Configure the vault
+        VaultConfig vaultConfig = new VaultConfig();
+        vaultConfig.setVaultId("<YOUR_VAULT_ID_1>"); // Replace with the ID of the vault
+        vaultConfig.setClusterId("<YOUR_CLUSTER_ID_1>"); // Replace with the cluster ID of the vault
+        vaultConfig.setEnv(Env.PROD); // Set the environment (e.g., DEV, STAGE, PROD)
+        vaultConfig.setCredentials(credentials); // Associate the credentials with the vault
+
+        // Step 3: Set up credentials for the Skyflow client
+        Credentials skyflowCredentials = new Credentials();
+        skyflowCredentials.setCredentialsString("<YOUR_CREDENTIALS_STRING>"); // Replace with the actual credentials string
+
+        // Step 4: Create a Skyflow client and add vault configurations
+        Skyflow skyflowClient = Skyflow.builder()
+                .setLogLevel(LogLevel.ERROR) // Enable debugging for detailed logs
+                .addVaultConfig(vaultConfig)      // Add the vault configuration
+                .addSkyflowCredentials(skyflowCredentials) // Add general Skyflow credentials
+                .build();
+
+        // Step 5: Update records with TokenMode enabled
+        // DEPRECATED: use "skyflowId" key instead of "skyflow_id"
+        try {
+            HashMap<String, Object> data1 = new HashMap<>();
+            data1.put("skyflow_id", "<YOUR_SKYFLOW_ID>"); // @deprecated — use "skyflowId"
+            data1.put("<COLUMN_NAME_1>", "<COLUMN_VALUE_1>"); // Replace with column name and value to update
+            data1.put("<COLUMN_NAME_2>", "<COLUMN_VALUE_2>"); // Replace with another column name and value
+
+            HashMap<String, Object> tokens = new HashMap<>();
+            tokens.put("<COLUMN_NAME_2>", "<TOKEN_VALUE_2>"); // Replace with the token for COLUMN_NAME_2
+
+            UpdateRequest updateRequest1 = UpdateRequest.builder()
+                    .table("<TABLE_NAME>") // Replace with the table name
+                    .tokenMode(TokenMode.ENABLE) // Enable TokenMode for token validation
+                    .data(data1) // Data to update
+                    .tokens(tokens) // Provide tokens for TokenMode columns
+                    .returnTokens(true) // Return tokens along with the update response
+                    .build();
+
+            UpdateResponse updateResponse1 = skyflowClient.vault().update(updateRequest1); // Perform the update
+            System.out.println("Update Response (TokenMode Enabled): " + updateResponse1);
+        } catch (SkyflowException e) {
+            System.out.println("Error during update with TokenMode enabled:");
+            e.printStackTrace();
+        }
+
+        // Step 6: Update records with TokenMode disabled
+        // DEPRECATED: use "skyflowId" key instead of "skyflow_id"
+        try {
+            HashMap<String, Object> data2 = new HashMap<>();
+            data2.put("skyflow_id", "<YOUR_SKYFLOW_ID>"); // @deprecated — use "skyflowId"
+            data2.put("<COLUMN_NAME_1>", "<COLUMN_VALUE_1>"); // Replace with column name and value to update
+            data2.put("<COLUMN_NAME_2>", "<COLUMN_VALUE_2>"); // Replace with another column name and value
+
+            UpdateRequest updateRequest2 = UpdateRequest.builder()
+                    .table("<TABLE_NAME>") // Replace with the table name
+                    .tokenMode(TokenMode.DISABLE) // Disable TokenMode
+                    .data(data2) // Data to update
+                    .returnTokens(false) // Do not return tokens
+                    .build();
+
+            UpdateResponse updateResponse2 = skyflowClient.vault().update(updateRequest2); // Perform the update
+            System.out.println("Update Response (TokenMode Disabled): " + updateResponse2);
+        } catch (SkyflowException e) {
+            System.out.println("Error during update with TokenMode disabled:" + e);
+        }
+    }
+}

src/main/java/com/skyflow/Skyflow.java

@@ -74,11 +74,18 @@ public Skyflow updateSkyflowCredentials(Credentials credentials) throws SkyflowE
         return this;
     }
 
-    public Skyflow updateLogLevel(LogLevel logLevel) {
+    public Skyflow setLogLevel(LogLevel logLevel) {
         this.builder.setLogLevel(logLevel);
         return this;
     }
 
+    /** @deprecated Use {@link #setLogLevel(LogLevel)} instead. */
+    @Deprecated(since = "2.1", forRemoval = true)
+    public Skyflow updateLogLevel(LogLevel logLevel) {
+        LogUtil.printWarningLog(InfoLogs.DEPRECATED_UPDATE_LOG_LEVEL.getLog());
+        return setLogLevel(logLevel);
+    }
+
     public LogLevel getLogLevel() {
         return this.builder.logLevel;
     }

src/main/java/com/skyflow/errors/SkyflowException.java

@@ -9,6 +9,33 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Exception thrown by all Skyflow SDK operations.
+ *
+ * <p>There are two broad categories of errors:
+ *
+ * <ul>
+ *   <li><b>Validation errors</b> — caught before any network call is made (e.g. missing table,
+ *       empty token list). These always have {@code httpCode = 400} and an empty
+ *       {@link #getDetails()} array. {@link #getRequestId()} and {@link #getGrpcCode()} are
+ *       {@code null}.
+ *   <li><b>API errors</b> — returned by the Skyflow server. The HTTP status code, gRPC code,
+ *       human-readable status string, error message, and request ID are all parsed from the
+ *       response and available via the corresponding getters.
+ * </ul>
+ *
+ * <p>Typical error-handling pattern:
+ * <pre>{@code
+ * try {
+ *     InsertResponse response = vault.insert(request);
+ * } catch (SkyflowException e) {
+ *     System.err.println("HTTP " + e.getHttpCode() + " — " + e.getMessage());
+ *     if (e.getRequestId() != null) {
+ *         System.err.println("Request ID: " + e.getRequestId());
+ *     }
+ * }
+ * }</pre>
+ */
 public class SkyflowException extends Exception {
     private String requestId;
     private Integer grpcCode;
@@ -33,6 +60,11 @@ public SkyflowException(String message, Throwable cause) {
         this.message = message;
     }
 
+    /**
+     * Constructs a validation error with a fixed HTTP 400 status.
+     * {@link #getDetails()} returns an empty array; {@link #getRequestId()} and
+     * {@link #getGrpcCode()} return {@code null}.
+     */
     public SkyflowException(int code, String message) {
         super(message);
         this.httpCode = code;
@@ -41,6 +73,13 @@ public SkyflowException(int code, String message) {
         this.details = new JsonArray();
     }
 
+    /**
+     * Constructs an API error from an HTTP response.
+     * Parses the JSON error body to populate {@link #getMessage()}, {@link #getGrpcCode()},
+     * {@link #getHttpStatus()}, and {@link #getDetails()}. The request ID is read from the
+     * {@code x-request-id} response header. If the body cannot be parsed, falls back to the
+     * raw body string as the message.
+     */
     public SkyflowException(int httpCode, Throwable cause, Map<String, List<String>> responseHeaders, String responseBody) {
         super(cause);
         this.httpCode = httpCode > 0 ? httpCode : 400;
@@ -65,6 +104,10 @@ private void setResponseBody(String responseBody, Map<String, List<String>> resp
         }
     }
 
+    /**
+     * Returns the {@code x-request-id} from the server response, useful for support escalations.
+     * {@code null} for validation errors that never reached the server.
+     */
     public String getRequestId() {
         return requestId;
     }
@@ -89,10 +132,19 @@ private void setHttpStatus() {
         this.httpStatus = statusElement == null ? null : statusElement.getAsString();
     }
 
+    /**
+     * Returns the HTTP status code (e.g. 400, 404, 500).
+     * Defaults to 400 when the server returned a non-positive code.
+     */
     public int getHttpCode() {
         return httpCode;
     }
 
+    /**
+     * Returns additional error details from the server response, or an empty array for
+     * validation errors. Never {@code null} for validation errors; may be {@code null} for
+     * API errors whose response body contained no {@code details} field.
+     */
     public JsonArray getDetails() {
         return details;
     }
@@ -112,10 +164,18 @@ private void setDetails(Map<String, List<String>> responseHeaders) {
         }
     }
 
+    /**
+     * Returns the gRPC status code from the server response.
+     * {@code null} for validation errors and API responses that omit this field.
+     */
     public Integer getGrpcCode() {
         return grpcCode;
     }
 
+    /**
+     * Returns the human-readable HTTP status string from the server response (e.g.
+     * {@code "Bad Request"}, {@code "Not Found"}).
+     */
     public String getHttpStatus() {
         return httpStatus;
     }

src/main/java/com/skyflow/logs/InfoLogs.java

@@ -100,7 +100,8 @@ public enum InfoLogs {
     DEPRECATED_SKYFLOW_ID_KEY("[DEPRECATED] Response key 'skyflow_id' is deprecated and will be removed in an upcoming release. Use 'skyflowId' instead."),
     DEPRECATED_SKYFLOW_ID_REQUEST_KEY("[DEPRECATED] Request data key 'skyflow_id' is deprecated and will be removed in an upcoming release. Use 'skyflowId' instead."),
     DEPRECATED_DOWNLOAD_URL("[DEPRECATED] Method 'downloadURL()' is deprecated and will be removed in an upcoming release. Use 'downloadUrl()' instead."),
-    DEPRECATED_GET_BYOT("[DEPRECATED] Method 'getBYOT()' is deprecated and will be removed in an upcoming release. Use 'getByot()' instead.");
+    DEPRECATED_GET_BYOT("[DEPRECATED] Method 'getBYOT()' is deprecated and will be removed in an upcoming release. Use 'getByot()' instead."),
+    DEPRECATED_UPDATE_LOG_LEVEL("[DEPRECATED] Method 'updateLogLevel()' is deprecated and will be removed in an upcoming release. Use 'setLogLevel()' instead.");
 
 
 

src/main/java/com/skyflow/vault/controller/VaultController.java

@@ -103,7 +103,12 @@ private static synchronized HashMap<String, Object> getFormattedBatchInsertRecor
         if (records != null) {
             for (JsonElement recordElement : records) {
                 JsonObject recordObject = recordElement.getAsJsonObject();
-                insertRecord.put("skyflowId", recordObject.get("skyflow_id").getAsString());
+                if (recordObject.has("skyflowId")) {
+                    insertRecord.put("skyflowId", recordObject.get("skyflowId").getAsString());
+                } else if (recordObject.has("skyflow_id")) {
+                    insertRecord.put("skyflowId", recordObject.get("skyflow_id").getAsString());
+                    LogUtil.printWarningLog(InfoLogs.DEPRECATED_SKYFLOW_ID_KEY.getLog());
+                }
                 JsonElement tokensElement = recordObject.get("tokens");
                 if (tokensElement != null) {
                     insertRecord.putAll(tokensElement.getAsJsonObject().asMap());