SK-3061: make DetokenizeResponseRecord.getMetadata() typed (#410)

* SK-3061: make DetokenizeResponseRecord.getMetadata() typed

metadata was a raw Map<String, Object>, requiring callers to cast into it
to reach skyflowId/tableName - the same usability gap Token closed for
InsertResponseRecord.getTokens(). Added DetokenizeMetadata (getSkyflowId(),
getTableName()) and made getMetadata() itself return it, matching how
getTokens() was made typed directly rather than adding a second accessor.

DetokenizeMetadata.parseMetadata(Map<String, Object>) normalizes the wire
shape - the proto's own literal example uses {"table": ..., "skyflowID": ...},
but Utils.java's existing handling already renamed skyflowID -> skyflowId
before this reached the record constructor, so parseMetadata accepts either
casing for both keys and moves that normalization out of Utils.java and
into one place, alongside the typing.

This changes DetokenizeResponseRecord/BulkDetokenizeResponseRecord's
metadata constructor parameter and getMetadata()'s return type from
Map<String, Object> to DetokenizeMetadata - a japicmp-breaking change,
same shape as the earlier getTokens() typing. Regenerated
flowvault/api-report/skyflow-flowvault-java.baseline.jar via
scripts/contract-snapshot-update.sh flowvault.

Updated README's Bulk Detokenize section (JSON sample + a typed-access
snippet) and every test constructing a record with a raw metadata map.

mvn -pl common,flowvault -am test -> 702 tests, 0 failures.
mvn -pl common,flowvault -am verify -> BUILD SUCCESS against the
regenerated baseline.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* SK-3061: add flowdb/unrenamed to cspell dictionary

Flagged by the cspell CI check on PR #410 - both words come from the
DetokenizeMetadata Javadoc/test comments referencing flowdb_dp_apis.proto
and describing the wire's unrenamed table key.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* SK-3061: add matching response-iteration snippets to Bulk Tokenize/Delete Tokens

Bulk Insert and Bulk Detokenize's README sections each show a code snippet
iterating the response; Bulk Tokenize and Bulk Delete Tokens only had a
JSON sample with no matching Java. Added one to each, same pattern:

- Bulk Tokenize: outer loop over records, inner loop over each record's
  tokens (it reports at two levels - see the paragraph directly above).
- Bulk Delete Tokens: single loop over records, success/error branch on
  getError().

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: Devesh-Skyflow

.cspell.json

@@ -111,7 +111,9 @@
     "recordss",
     "rarr",
     "servname",
-    "nodename"
+    "nodename",
+    "flowdb",
+    "unrenamed"
   ],
   "languageSettings": [
     {

flowvault/README.md

@@ -580,6 +580,18 @@ Sample response:
 
 Tokenize reports at **two** levels: one entry per input value in `records`, and inside each of those, one entry per requested token group in `tokens`. Because a single value can map to several token groups, the summary distinguishes fully tokenized values (`totalTokenized`), partially tokenized values where some groups succeeded and others failed (`totalPartial`), and fully failed values (`totalFailed`). The three always add up to `totalTokens`, which counts input values, not tokens produced.
 
+```java
+for (BulkTokenizeResponseRecord record : tokenizeResponse.getRecords()) {
+    for (TokenizeResponseToken token : record.getTokens()) {
+        if (token.getError() == null) {
+            System.out.println(record.getValue() + " -> " + token.getTokenGroupName() + " = " + token.getToken());
+        } else {
+            System.out.println(record.getValue() + " -> " + token.getTokenGroupName() + " failed: " + token.getError());
+        }
+    }
+}
+```
+
 # Bulk Detokenize
 
 Detokenize many tokens in one call, optionally overriding the redaction applied per token group via `tokenGroupRedactions`.
@@ -640,7 +652,7 @@ Sample response:
       "requestId": null,
       "value": "4111111111111111",
       "tokenGroupName": "card_number_cg",
-      "metadata": { "table": "table1", "skyflowId": "9fac9201-7b8a-4446-93f8-5244e1213bd1" },
+      "metadata": { "skyflowId": "9fac9201-7b8a-4446-93f8-5244e1213bd1", "tableName": "table1" },
       "httpCode": 200,
       "token": "5479-4229-4622-1393",
       "error": null
@@ -659,6 +671,16 @@ Sample response:
 }
 ```
 
+`record.getMetadata()` is typed as a `DetokenizeMetadata` with `getSkyflowId()`/`getTableName()` — no casting into the raw map required (`null` on records that errored, same as above):
+
+```java
+for (BulkDetokenizeResponseRecord record : detokenizeResponse.getRecords()) {
+    if (record.getMetadata() != null) {
+        System.out.println(record.getMetadata().getSkyflowId() + " / " + record.getMetadata().getTableName());
+    }
+}
+```
+
 Use `detokenizeResponse.getTokensToRetry()` to get back only the tokens worth resubmitting.
 
 # Bulk Delete Tokens
@@ -713,6 +735,16 @@ Sample response:
 }
 ```
 
+```java
+for (BulkDeleteTokensResponseRecord record : deleteTokensResponse.getRecords()) {
+    if (record.getError() == null) {
+        System.out.println(record.getToken() + " deleted");
+    } else {
+        System.out.println(record.getToken() + " failed (" + record.getHttpCode() + "): " + record.getError());
+    }
+}
+```
+
 Use `deleteTokensResponse.getTokensToRetry()` to get back only the tokens worth resubmitting.
 
 # Custom Request Headers

flowvault/api-report/skyflow-flowvault-java.baseline.jar

@@ -41,6 +41,7 @@
 import com.skyflow.vault.data.BulkDetokenizeRequest;
 import com.skyflow.vault.data.BulkDetokenizeResponse;
 import com.skyflow.vault.data.BulkDetokenizeResponseRecord;
+import com.skyflow.vault.data.DetokenizeMetadata;
 import com.skyflow.vault.data.BulkInsertRequest;
 import com.skyflow.vault.data.BulkInsertResponse;
 import com.skyflow.vault.data.BulkInsertResponseRecord;
@@ -782,14 +783,7 @@ public static BulkDetokenizeResponse formatBulkDetokenizeResponse(V1FlowDetokeni
             int recordsSize = record.size();
             for (int index = 0; index < recordsSize; index++) {
                 V1FlowDetokenizeResponseObject current = record.get(index);
-                Map<String, Object> data = null;
-                if(current.getMetadata().isPresent()){
-                    data = current.getMetadata().get();
-                    if (data.containsKey("skyflowID")) {
-                        Object value = data.remove("skyflowID");
-                        data.put("skyflowId", value);
-                    }
-                }
+                DetokenizeMetadata metadata = DetokenizeMetadata.parseMetadata(current.getMetadata().orElse(null));
                 String reqID = null;
                 if(current.getError().isPresent()){
                     reqID = extractRequestId(headers);
@@ -799,7 +793,7 @@ public static BulkDetokenizeResponse formatBulkDetokenizeResponse(V1FlowDetokeni
                         current.getToken().orElse(null),
                         current.getValue().orElse(null),
                         current.getTokenGroupName().orElse(null),
-                        data,
+                        metadata,
                         current.getHttpCode().orElse(current.getError().isPresent() ? 500 : 200),
                         current.getError().orElse(null),
                         reqID));

flowvault/src/main/java/com/skyflow/utils/Utils.java

@@ -2,16 +2,14 @@
 
 import com.google.gson.Gson;
 
-import java.util.Map;
-
 // Bulk counterpart of DetokenizeResponseRecord. Adds the caller-facing position of the token
 // in the submitted payload; all other fields are inherited.
 public class BulkDetokenizeResponseRecord extends DetokenizeResponseRecord {
     private final int index;
     private final String requestId;
 
     public BulkDetokenizeResponseRecord(int index, String token, Object value, String tokenGroupName,
-                                        Map<String, Object> metadata, int httpCode, String error,
+                                        DetokenizeMetadata metadata, int httpCode, String error,
                                         String requestId) {
         super(token, value, tokenGroupName, metadata, httpCode, error);
         this.index = index;

flowvault/src/main/java/com/skyflow/vault/data/BulkDetokenizeResponseRecord.java

@@ -0,0 +1,55 @@
+package com.skyflow.vault.data;
+
+import com.google.gson.Gson;
+import com.google.gson.annotations.Expose;
+
+import java.util.Map;
+
+/**
+ * Typed shape of a detokenize record's {@code metadata}. The wire response nests the record's
+ * skyflow id and table name here, under the literal keys {@code skyflowID} and {@code table}
+ * (see {@code flowdb_dp_apis.proto}) — {@link #parseMetadata(Map)} normalizes both into the
+ * camelCase, {@code tableName}-shaped accessors below.
+ */
+public class DetokenizeMetadata {
+    @Expose(serialize = true)
+    private final String skyflowId;
+    @Expose(serialize = true)
+    private final String tableName;
+
+    public DetokenizeMetadata(String skyflowId, String tableName) {
+        this.skyflowId = skyflowId;
+        this.tableName = tableName;
+    }
+
+    public String getSkyflowId() {
+        return skyflowId;
+    }
+
+    public String getTableName() {
+        return tableName;
+    }
+
+    @Override
+    public String toString() {
+        Gson gson = new Gson().newBuilder().serializeNulls().create();
+        return gson.toJson(this);
+    }
+
+    /**
+     * Parses the raw wire-shaped metadata map (keys {@code skyflowID}/{@code skyflowId} and
+     * {@code table}/{@code tableName} — the API has been observed to send either casing) into a
+     * {@link DetokenizeMetadata}. Returns {@code null} for {@code null} input, matching the
+     * record-level metadata field being absent entirely on error records.
+     */
+    public static DetokenizeMetadata parseMetadata(Map<String, Object> rawMetadata) {
+        if (rawMetadata == null) {
+            return null;
+        }
+        Object skyflowId = rawMetadata.containsKey("skyflowId") ? rawMetadata.get("skyflowId") : rawMetadata.get("skyflowID");
+        Object tableName = rawMetadata.containsKey("tableName") ? rawMetadata.get("tableName") : rawMetadata.get("table");
+        return new DetokenizeMetadata(
+                skyflowId != null ? skyflowId.toString() : null,
+                tableName != null ? tableName.toString() : null);
+    }
+}

flowvault/src/main/java/com/skyflow/vault/data/DetokenizeMetadata.java

@@ -1,16 +1,14 @@
 package com.skyflow.vault.data;
 
-import java.util.Map;
-
 public class DetokenizeResponseRecord extends BaseDetokenizeRecordResponse {
     // Passed straight through from V1FlowDetokenizeResponseObject.getValue() (Optional<Object>).
     private final Object value;
     private final String tokenGroupName;
-    private final Map<String, Object> metadata;
+    private final DetokenizeMetadata metadata;
     private final int httpCode;
 
     public DetokenizeResponseRecord(String token, Object value, String tokenGroupName,
-                                     Map<String, Object> metadata, int httpCode, String error) {
+                                     DetokenizeMetadata metadata, int httpCode, String error) {
         super(token, error);
         this.value = value;
         this.tokenGroupName = tokenGroupName;
@@ -26,7 +24,13 @@ public String getTokenGroupName() {
         return tokenGroupName;
     }
 
-    public Map<String, Object> getMetadata() {
+    /**
+     * The record's skyflowId/tableName, typed. The API models this generically (see
+     * {@link DetokenizeMetadata#parseMetadata(java.util.Map)}), but the SDK parses it here so
+     * callers get {@link DetokenizeMetadata#getSkyflowId()}/{@link DetokenizeMetadata#getTableName()}
+     * directly, with no casting required.
+     */
+    public DetokenizeMetadata getMetadata() {
         return metadata;
     }
 

flowvault/src/main/java/com/skyflow/vault/data/DetokenizeResponseRecord.java

@@ -158,8 +158,7 @@ public void testDetokenizeRequest_defaultsAreNull() {
 
     @Test
     public void testDetokenizeResponseRecord_gettersReturnConstructorValues() {
-        Map<String, Object> metadata = new HashMap<>();
-        metadata.put("key", "value");
+        DetokenizeMetadata metadata = new DetokenizeMetadata("skyflow-id-1", "table1");
 
         DetokenizeResponseRecord response = new DetokenizeResponseRecord(
                 "tok-1", "secret-value", "group1", metadata, 200, null);

flowvault/src/test/java/com/skyflow/vault/data/RequestResponseWrapperTests.java

@@ -14,7 +14,7 @@
  * constructor logic or toString() serialization: {@link Token}, {@link TokenizeResponseToken},
  * {@link TokenizeResponseRecord}, {@link BulkTokenizeResponseRecord}, {@link TokenizeSummary},
  * {@link DeleteTokensRecord}, {@link BulkDeleteTokensResponseRecord},
- * {@link DeleteTokensSummary}, {@link DetokenizeSummary},
+ * {@link DeleteTokensSummary}, {@link DetokenizeSummary}, {@link DetokenizeMetadata},
  * {@link ErrorRecord} and {@link DetokenizeResponseObject}.
  */
 public class ResponseComponentTests {
@@ -531,8 +531,7 @@ public void testErrorRecord_toStringNotNull() {
 
     @Test
     public void testBulkDetokenizeResponseRecord_gettersReturnConstructorValues() {
-        Map<String, Object> metadata = new HashMap<>();
-        metadata.put("key", "value");
+        DetokenizeMetadata metadata = new DetokenizeMetadata("skyflow-id-1", "table1");
 
         BulkDetokenizeResponseRecord record = new BulkDetokenizeResponseRecord(
                 4, "tok-1", "secret-value", "group1", metadata, 200, null, null);
@@ -575,4 +574,77 @@ public void testBulkDetokenizeResponseRecord_toStringSerializesNulls() {
         Assert.assertTrue(json.contains("\"token\":\"tok\""));
         Assert.assertTrue(json.contains("\"error\":null"));
     }
+
+    // ── DetokenizeMetadata ────────────────────────────────────────────────────
+
+    @Test
+    public void testDetokenizeMetadata_gettersReturnConstructorValues() {
+        DetokenizeMetadata metadata = new DetokenizeMetadata("skyflow-id-1", "table1");
+
+        Assert.assertEquals("skyflow-id-1", metadata.getSkyflowId());
+        Assert.assertEquals("table1", metadata.getTableName());
+    }
+
+    @Test
+    public void testDetokenizeMetadata_toStringSerializesFields() {
+        String json = new DetokenizeMetadata("skyflow-id-1", "table1").toString();
+
+        Assert.assertTrue(json.contains("\"skyflowId\":\"skyflow-id-1\""));
+        Assert.assertTrue(json.contains("\"tableName\":\"table1\""));
+    }
+
+    @Test
+    public void testParseMetadata_returnsNullWhenRawMetadataIsNull() {
+        Assert.assertNull(DetokenizeMetadata.parseMetadata(null));
+    }
+
+    @Test
+    public void testParseMetadata_parsesTheCamelCaseWireShape() {
+        // The shape Utils.formatBulkDetokenizeResponse actually hands this after its own
+        // skyflowID -> skyflowId rename; table is left as-is on the wire.
+        Map<String, Object> raw = new HashMap<>();
+        raw.put("skyflowId", "skyflow-id-1");
+        raw.put("table", "table1");
+
+        DetokenizeMetadata metadata = DetokenizeMetadata.parseMetadata(raw);
+
+        Assert.assertEquals("skyflow-id-1", metadata.getSkyflowId());
+        Assert.assertEquals("table1", metadata.getTableName());
+    }
+
+    @Test
+    public void testParseMetadata_prefersAnAlreadyCamelCasedTableNameKeyOverTable() {
+        // Exercises the containsKey("tableName") branch directly - every other test only ever
+        // supplies the wire's "table" key, never "tableName" itself.
+        Map<String, Object> raw = new HashMap<>();
+        raw.put("skyflowId", "skyflow-id-1");
+        raw.put("tableName", "table1");
+        raw.put("table", "should-be-ignored");
+
+        DetokenizeMetadata metadata = DetokenizeMetadata.parseMetadata(raw);
+
+        Assert.assertEquals("table1", metadata.getTableName());
+    }
+
+    @Test
+    public void testParseMetadata_parsesTheLiteralProtoWireShape() {
+        // flowdb_dp_apis.proto's own example value uses this exact casing/naming -
+        // {"table": "table1", "skyflowID": "..."} - unrenamed.
+        Map<String, Object> raw = new HashMap<>();
+        raw.put("skyflowID", "skyflow-id-1");
+        raw.put("table", "table1");
+
+        DetokenizeMetadata metadata = DetokenizeMetadata.parseMetadata(raw);
+
+        Assert.assertEquals("skyflow-id-1", metadata.getSkyflowId());
+        Assert.assertEquals("table1", metadata.getTableName());
+    }
+
+    @Test
+    public void testParseMetadata_missingKeysParseAsNull() {
+        DetokenizeMetadata metadata = DetokenizeMetadata.parseMetadata(new HashMap<>());
+
+        Assert.assertNull(metadata.getSkyflowId());
+        Assert.assertNull(metadata.getTableName());
+    }
 }