From 0066e3514d58bcc65a4ce3e4dcf6422d7801cdeb Mon Sep 17 00:00:00 2001 From: Aadarsh Date: Tue, 2 Jun 2026 17:45:07 +0530 Subject: [PATCH 1/2] SK-2709: Fix Gaps in readme and samples --- README.md | 359 +++++++++++++++++- .../example/detect/ReidentifyTextExample.java | 95 +++++ .../com/example/vault/DetokenizeExample.java | 38 +- .../java/com/example/vault/GetExample.java | 55 ++- 4 files changed, 526 insertions(+), 21 deletions(-) create mode 100644 samples/src/main/java/com/example/detect/ReidentifyTextExample.java diff --git a/README.md b/README.md index e041ca2e..c446e896 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,10 @@ The Skyflow Java SDK is designed to help with integrating Skyflow into a Java ba - [Initialize the client](#initialize-the-client) - [Insert data into the vault](#insert-data-into-the-vault) - [Vault](#vault) + - [VaultController](#vaultcontroller) - [Insert data into the vault](#insert-data-into-the-vault-1) - [Detokenize](#detokenize) + - [DetokenizeRecordResponse](#detokenizerecordresponse) - [Tokenize](#tokenize) - [Get](#get) - [Get by skyflow IDS](#get-by-skyflow-ids) @@ -37,13 +39,18 @@ The Skyflow Java SDK is designed to help with integrating Skyflow into a Java ba - [Delete](#delete) - [Query](#query) - [Upload File](#upload-file) + - [Detect](#detect) - [Deidentify Text](#deidentify-text) - [Reidentify Text](#reidentify-text) - [Deidentify File](#deidentify-file) - [Get Run](#get-run) + - [Detect response types](#detect-response-types) + - [Detect enums](#detect-enums) - [Connections](#connections) + - [ConnectionController](#connectioncontroller) - [Invoke a connection](#invoke-a-connection) +- [Client Management](#client-management) - [Authenticate with bearer tokens](#authenticate-with-bearer-tokens) - [Generate a bearer token](#generate-a-bearer-token) - [Generate bearer tokens with context](#generate-bearer-tokens-with-context) @@ -228,6 +235,7 @@ Notes: - If both Skyflow common credentials and individual credentials at the configuration level are specified, the individual credentials at the configuration level will take precedence. - If neither Skyflow common credentials nor individual configuration-level credentials are provided, the SDK attempts to retrieve credentials from the `SKYFLOW_CREDENTIALS` environment variable. - All Vault operations require a client instance. +- `Credentials.setContext()` accepts either a `String` or a `Map` for context-aware authorization. See [Generate bearer tokens with context](#generate-bearer-tokens-with-context) for full usage. ### Insert data into the vault @@ -308,6 +316,33 @@ Skyflow returns tokens for the record that was just inserted. The [Vault](https://github.com/skyflowapi/skyflow-java/tree/main/samples/src/main/java/com/example/vault) module performs operations on the vault, including inserting records, detokenizing tokens, and retrieving tokens associated with a `skyflow_id`. +## VaultController + +`VaultController` is the class returned by `skyflowClient.vault()` and `skyflowClient.vault(vaultId)`. All vault operations are called on this object. + +```java +// Uses the default (first configured) vault +VaultController vault = skyflowClient.vault(); + +// Uses a specific vault by ID +VaultController vault = skyflowClient.vault(""); +``` + +**Methods:** + +| Method | Parameters | Returns | Description | +|--------|-----------|---------|-------------| +| `insert(InsertRequest)` | `InsertRequest` | `InsertResponse` | Insert one or more records | +| `detokenize(DetokenizeRequest)` | `DetokenizeRequest` | `DetokenizeResponse` | Detokenize tokens to their original values | +| `tokenize(TokenizeRequest)` | `TokenizeRequest` | `TokenizeResponse` | Tokenize sensitive values | +| `get(GetRequest)` | `GetRequest` | `GetResponse` | Retrieve records by Skyflow ID or column value | +| `update(UpdateRequest)` | `UpdateRequest` | `UpdateResponse` | Update a record by Skyflow ID | +| `delete(DeleteRequest)` | `DeleteRequest` | `DeleteResponse` | Delete records by Skyflow ID | +| `query(QueryRequest)` | `QueryRequest` | `QueryResponse` | Execute a SQL query | +| `uploadFile(FileUploadRequest)` | `FileUploadRequest` | `FileUploadResponse` | Upload a file to a vault column | + +All methods throw `SkyflowException` on error. + ## Insert data into the vault Apart from using the `insert` method to insert data into your vault covered in [Quickstart](#quickstart), you can also specify options in `InsertRequest`, such as returning tokenized data, upserting records, or continuing the operation in case of errors. @@ -532,6 +567,20 @@ Skyflow returns tokens, with `upsert` support, for the record you just inserted. To retrieve tokens from your vault, use the `detokenize` method. The `DetokenizeRequest` class requires a list of detokenization data as input. Additionally, you can provide optional parameters, such as the redaction type and the option to continue on error. +### DetokenizeData + +Each entry in the detokenize list is a `DetokenizeData` object pairing a token with its desired redaction type. + +| Constructor | Description | +|-------------|-------------| +| `new DetokenizeData(String token)` | Detokenize with default redaction (`RedactionType.DEFAULT`) | +| `new DetokenizeData(String token, RedactionType redactionType)` | Detokenize with a specific redaction type | + +| Method | Return type | Description | +|--------|------------|-------------| +| `getToken()` | `String` | The token value | +| `getRedactionType()` | `RedactionType` | The redaction type applied to the result | + ### Construct a detokenize request ```java @@ -652,6 +701,36 @@ Sample response: ``` +### DetokenizeRecordResponse + +`DetokenizeResponse.getDetokenizedFields()` and `DetokenizeResponse.getErrors()` each return a `List`. Use this class to read individual token results: + +```java +DetokenizeResponse detokenizeResponse = skyflowClient.vault("").detokenize(detokenizeRequest); + +for (DetokenizeRecordResponse record : detokenizeResponse.getDetokenizedFields()) { + System.out.println("Token : " + record.getToken()); + System.out.println("Value : " + record.getValue()); + System.out.println("Type : " + record.getType()); + System.out.println("ReqID : " + record.getRequestId()); +} + +for (DetokenizeRecordResponse err : detokenizeResponse.getErrors()) { + System.out.println("Failed token : " + err.getToken()); + System.out.println("Error : " + err.getError()); +} +``` + +**`DetokenizeRecordResponse` methods:** + +| Method | Return type | Description | +|--------|------------|-------------| +| `getToken()` | `String` | The original token value | +| `getValue()` | `String` | The detokenized (plaintext) value; `null` on error | +| `getType()` | `String` | Data type of the value (e.g. `"STRING"`); `null` if not set | +| `getError()` | `String` | Error message when detokenization failed; `null` on success | +| `getRequestId()` | `String` | The `x-request-id` for the underlying API call | + ### An example of a detokenize call with `continueOnError` option: ```java @@ -732,6 +811,27 @@ Tokenization replaces sensitive data with unique identifier tokens. This approac To tokenize data, use the `tokenize` method. The `TokenizeRequest` class creates a tokenize request. In this request, you specify the `values` parameter, which is a list of `ColumnValue` objects. Each `ColumnValue` contains two properties: `value` and `columnGroup`. +### ColumnValue + +`ColumnValue` pairs a sensitive value with the column group that defines how it is tokenized. + +```java +ColumnValue columnValue = ColumnValue.builder() + .value("") // the data to tokenize + .columnGroup("") // the vault column group name + .build(); +``` + +| Builder method | Description | +|---------------|-------------| +| `.value(String)` | The sensitive value to tokenize | +| `.columnGroup(String)` | The column group in the vault that defines the tokenization policy | + +| Getter | Return type | Description | +|--------|------------|-------------| +| `getValue()` | `String` | The original value | +| `getColumnGroup()` | `String` | The column group name | + ### Construct a tokenize request ```java @@ -1614,7 +1714,26 @@ Sample response: ``` # Detect -Skyflow Detect enables you to deidentify and reidentify sensitive data in text and files, supporting advanced privacy-preserving workflows. The Detect API supports the following operations: +Skyflow Detect enables you to deidentify and reidentify sensitive data in text and files, supporting advanced privacy-preserving workflows. + +`DetectController` is the class returned by `skyflowClient.detect()` and `skyflowClient.detect(vaultId)`. + +```java +// Uses the default (first configured) vault +DetectController detect = skyflowClient.detect(); + +// Uses a specific vault by ID +DetectController detect = skyflowClient.detect(""); +``` + +**Methods:** + +| Method | Parameters | Returns | Description | +|--------|-----------|---------|-------------| +| `deidentifyText(DeidentifyTextRequest)` | `DeidentifyTextRequest` | `DeidentifyTextResponse` | Deidentify sensitive entities in text | +| `reidentifyText(ReidentifyTextRequest)` | `ReidentifyTextRequest` | `ReidentifyTextResponse` | Restore original values from a deidentified text | +| `deidentifyFile(DeidentifyFileRequest)` | `DeidentifyFileRequest` | `DeidentifyFileResponse` | Deidentify sensitive data in a file | +| `getDetectRun(GetDetectRunRequest)` | `GetDetectRunRequest` | `DeidentifyFileResponse` | Poll for the result of an async file deidentification | ## Deidentify Text To deidentify text, use the `deidentifyText` method. The `DeidentifyTextRequest` class creates a deidentify text request, which includes the text to be deidentified. Additionally, you can provide optional parameters using the `DeidentifyTextOptions` class. @@ -1931,6 +2050,28 @@ Sample Response: ## Deidentify file To deidentify files, use the `deidentifyFile` method. The `DeidentifyFileRequest` class creates a deidentify file request, which includes the file to be deidentified (such as images, PDFs, audio, documents, spreadsheets, or presentations). Additionally, you can provide optional parameters using the DeidentifyFileOptions class to control how entities are detected and deidentified, as well as how the output is generated for different file types. +### AudioBleep + +`AudioBleep` controls how detected sensitive audio segments are replaced with a bleep tone. Used in `DeidentifyFileRequest.builder().bleep(audioBleep)` for audio files. + +```java +import com.skyflow.vault.detect.AudioBleep; + +AudioBleep audioBleep = AudioBleep.builder() + .frequency(1000D) // bleep tone frequency in Hz + .gain(0.5D) // bleep tone gain (volume level) + .startPadding(0.2D) // silence padding before the bleep (seconds) + .stopPadding(0.2D) // silence padding after the bleep (seconds) + .build(); +``` + +| Builder method | Type | Description | +|---------------|------|-------------| +| `.frequency(Double)` | `Double` | Tone frequency in Hz | +| `.gain(Double)` | `Double` | Tone gain (volume) | +| `.startPadding(Double)` | `Double` | Padding before the bleep in seconds | +| `.stopPadding(Double)` | `Double` | Padding after the bleep in seconds | + ### Construct an deidentify file request ```java @@ -2260,6 +2401,132 @@ Sample Response: ``` +## Detect response types + +The Detect API returns structured objects for detected entities. These types appear in `DeidentifyTextResponse.getEntities()` and `DeidentifyFileResponse.getEntities()`. + +### EntityInfo + +Represents a single detected entity in a text deidentification response. + +| Method | Return type | Description | +|--------|------------|-------------| +| `getToken()` | `String` | Placeholder token that replaced the entity in the processed text | +| `getValue()` | `String` | Original sensitive value that was detected | +| `getEntity()` | `String` | Entity type label (e.g. `"SSN"`, `"CREDIT_CARD"`) | +| `getTextIndex()` | `TextIndex` | Character positions of the entity in the **original** text | +| `getProcessedIndex()` | `TextIndex` | Character positions of the token in the **processed** text | +| `getScores()` | `Map` | Confidence scores per entity type (e.g. `{"SSN": 0.93}`) | + +### TextIndex + +Represents the start and end character positions of a detected entity. + +| Method | Return type | Description | +|--------|------------|-------------| +| `getStart()` | `int` | Inclusive start character index | +| `getEnd()` | `int` | Exclusive end character index | + +**Example:** + +```java +DeidentifyTextResponse response = skyflowClient.detect("").deidentifyText(request); + +for (EntityInfo entity : response.getEntities()) { + System.out.println("Entity : " + entity.getEntity()); + System.out.println("Value : " + entity.getValue()); + System.out.println("Token : " + entity.getToken()); + System.out.println("Start : " + entity.getTextIndex().getStart()); + System.out.println("End : " + entity.getTextIndex().getEnd()); + System.out.println("Score : " + entity.getScores().get(entity.getEntity())); +} +``` + +### FileEntityInfo + +Appears inside `DeidentifyFileResponse.getEntities()` — represents a detected-entity output file (e.g. a JSON file listing all found entities). + +| Method | Return type | Description | +|--------|------------|-------------| +| `getFile()` | `String` | Base64-encoded content of the entity output file | +| `getType()` | `String` | Output type (e.g. `"entities"`) | +| `getExtension()` | `String` | File extension of the output (e.g. `"json"`) | + +### FileInfo + +Wraps metadata about a file used in detect operations. + +| Method | Return type | Description | +|--------|------------|-------------| +| `getName()` | `String` | File name | +| `getSize()` | `long` | File size in bytes | +| `getType()` | `String` | MIME type (may be empty for some formats) | +| `getLastModified()` | `long` | Last modified timestamp (milliseconds since epoch) | + +## Detect enums + +### TokenType + +Controls how detected entities are tokenized in the output. Used in `TokenFormat.builder()`. + +| Value | Description | +|-------|-------------| +| `VAULT_TOKEN` | Store the entity in the vault and return a vault token | +| `ENTITY_UNIQUE_COUNTER` | Return a deterministic label with a counter suffix (default) | +| `ENTITY_ONLY` | Return only the entity label, without a counter | + +```java +import com.skyflow.enums.TokenType; + +TokenFormat tokenFormat = TokenFormat.builder() + .vaultToken(vaultTokenList) // uses VAULT_TOKEN + .entityOnly(entityOnlyList) // uses ENTITY_ONLY + .entityUniqueCounter(entityUniqueCounterList) // uses ENTITY_UNIQUE_COUNTER + .build(); +``` + +### DeidentifyFileStatus + +Returned in `DeidentifyFileResponse.getStatus()` to indicate the processing state of an async deidentify-file operation. + +| Value | Description | +|-------|-------------| +| `IN_PROGRESS` | File is still being processed | +| `SUCCESS` | Processing completed successfully | +| `FAILED` | Processing failed | +| `UNKNOWN` | Status could not be determined | + +```java +import com.skyflow.enums.DeidentifyFileStatus; + +DeidentifyFileResponse response = skyflowClient.detect("").getDetectRun(request); +if (DeidentifyFileStatus.SUCCESS.value().equals(response.getStatus())) { + // safe to read response.getFile() +} else if (DeidentifyFileStatus.IN_PROGRESS.value().equals(response.getStatus())) { + // poll again using the runId +} +``` + +### DetectOutputTranscriptions + +Controls the transcription format for audio file deidentification. Used in `DeidentifyFileRequest.builder().outputTranscription(DetectOutputTranscriptions)`. + +| Value | Description | +|-------|-------------| +| `TRANSCRIPTION` | Standard transcription of the audio | +| `DIARIZED_TRANSCRIPTION` | Transcription with speaker labels | +| `MEDICAL_TRANSCRIPTION` | Medical-domain transcription | +| `MEDICAL_DIARIZED_TRANSCRIPTION` | Medical-domain transcription with speaker labels | + +```java +import com.skyflow.enums.DetectOutputTranscriptions; + +DeidentifyFileRequest request = DeidentifyFileRequest.builder() + .file(fileInput) + .outputTranscription(DetectOutputTranscriptions.TRANSCRIPTION) + .build(); +``` + # Connections Skyflow Connections is a gateway service that uses tokenization to securely send and receive data between your systems and first- or third-party services. The [connections](https://github.com/skyflowapi/skyflow-java/tree/main/src/main/java/com/skyflow/vault/connection) module invokes both inbound and/or outbound connections. @@ -2267,6 +2534,24 @@ Skyflow Connections is a gateway service that uses tokenization to securely send - **Inbound connections**: Act as intermediaries between your client and server, tokenizing sensitive data before it reaches your backend, ensuring downstream services handle only tokenized data. - **Outbound connections**: Enable secure extraction of data from the vault and transfer it to third-party services via your backend server, such as processing checkout or card issuance flows. +## ConnectionController + +`ConnectionController` is the class returned by `skyflowClient.connection()` and `skyflowClient.connection(connectionId)`. All connection operations are called on this object. + +```java +// Uses the default (first configured) connection +ConnectionController connection = skyflowClient.connection(); + +// Uses a specific connection by ID +ConnectionController connection = skyflowClient.connection(""); +``` + +**Methods:** + +| Method | Parameters | Returns | Description | +|--------|-----------|---------|-------------| +| `invoke(InvokeConnectionRequest)` | `InvokeConnectionRequest` | `InvokeConnectionResponse` | Invoke an inbound or outbound connection | + ## Invoke a connection To invoke a connection, use the `invoke` method of the Skyflow client. @@ -2789,6 +3074,78 @@ public class DetokenizeExample { } ``` +# Client Management + +After the `Skyflow` client is built you can add, retrieve, update, or remove vault and connection configurations at runtime — without rebuilding the client. + +## Vault configuration management + +```java +import com.skyflow.config.VaultConfig; + +// Add a new vault at runtime +skyflowClient.addVaultConfig(newVaultConfig); + +// Retrieve the config for a specific vault +VaultConfig config = skyflowClient.getVaultConfig(""); + +// Update an existing vault config (match by vaultId) +skyflowClient.updateVaultConfig(updatedVaultConfig); + +// Remove a vault from the client +skyflowClient.removeVaultConfig(""); +``` + +## Connection configuration management + +```java +import com.skyflow.config.ConnectionConfig; + +// Add a new connection at runtime +skyflowClient.addConnectionConfig(newConnectionConfig); + +// Retrieve the config for a specific connection +ConnectionConfig config = skyflowClient.getConnectionConfig(""); + +// Update an existing connection config (match by connectionId) +skyflowClient.updateConnectionConfig(updatedConnectionConfig); + +// Remove a connection from the client +skyflowClient.removeConnectionConfig(""); +``` + +## Credentials and log level management + +```java +// Replace the Skyflow-level credentials used when vault/connection configs +// do not specify their own credentials +skyflowClient.updateSkyflowCredentials(newCredentials); + +// Update the log level after the client has been built +skyflowClient.updateLogLevel(LogLevel.DEBUG); + +// Read the current log level +LogLevel currentLevel = skyflowClient.getLogLevel(); +``` + +**Client management method reference:** + +| Method | Returns | Description | +|--------|---------|-------------| +| `addVaultConfig(VaultConfig)` | `Skyflow` | Add a vault configuration | +| `getVaultConfig(String vaultId)` | `VaultConfig` | Retrieve a vault configuration by ID | +| `updateVaultConfig(VaultConfig)` | `Skyflow` | Replace a vault configuration (matched by `vaultId`) | +| `removeVaultConfig(String vaultId)` | `Skyflow` | Remove a vault configuration | +| `addConnectionConfig(ConnectionConfig)` | `Skyflow` | Add a connection configuration | +| `getConnectionConfig(String connectionId)` | `ConnectionConfig` | Retrieve a connection configuration by ID | +| `updateConnectionConfig(ConnectionConfig)` | `Skyflow` | Replace a connection configuration | +| `removeConnectionConfig(String connectionId)` | `Skyflow` | Remove a connection configuration | +| `updateSkyflowCredentials(Credentials)` | `Skyflow` | Replace the client-level credentials | +| `updateLogLevel(LogLevel)` | `Skyflow` | Change the log level after initialization | +| `getLogLevel()` | `LogLevel` | Return the current log level | + +All mutating methods return the `Skyflow` instance for chaining and throw `SkyflowException` on validation errors. + # Error Handling The SDK uses `SkyflowException` for all errors — both client-side validation errors and server-side API errors. diff --git a/samples/src/main/java/com/example/detect/ReidentifyTextExample.java b/samples/src/main/java/com/example/detect/ReidentifyTextExample.java new file mode 100644 index 00000000..a06a2e62 --- /dev/null +++ b/samples/src/main/java/com/example/detect/ReidentifyTextExample.java @@ -0,0 +1,95 @@ +package com.example.detect; + +import com.skyflow.Skyflow; +import com.skyflow.config.Credentials; +import com.skyflow.config.VaultConfig; +import com.skyflow.enums.DetectEntities; +import com.skyflow.enums.Env; +import com.skyflow.enums.LogLevel; +import com.skyflow.errors.SkyflowException; +import com.skyflow.vault.detect.ReidentifyTextRequest; +import com.skyflow.vault.detect.ReidentifyTextResponse; + +import java.util.ArrayList; +import java.util.List; + +/** + * Skyflow Reidentify Text Example + * + * Demonstrates how to use the Skyflow SDK to reidentify (restore) sensitive values + * in a previously deidentified text string. This is the reverse of deidentifyText. + * + * Steps: + * 1. Configure credentials and vault. + * 2. Create a Skyflow client. + * 3. Build a ReidentifyTextRequest with the deidentified text and entity-display options. + * 4. Call reidentifyText and handle the response. + */ +public class ReidentifyTextExample { + + public static void main(String[] args) throws SkyflowException { + + // Step 1: Set up credentials + Credentials credentials = new Credentials(); + credentials.setPath(""); // Replace with path to your credentials JSON file + // Alternative authentication options (uncomment one if needed): + // credentials.setApiKey(""); + // credentials.setToken(""); + // credentials.setCredentialsString(""); + + // Step 2: Configure the vault + VaultConfig vaultConfig = new VaultConfig(); + vaultConfig.setVaultId(""); // Replace with your vault ID + vaultConfig.setClusterId(""); // Replace with your cluster ID (from vault URL) + vaultConfig.setEnv(Env.PROD); // Environment: PROD, SANDBOX, STAGE, or DEV + vaultConfig.setCredentials(credentials); // Attach credentials to this vault + + // Step 3: Create a Skyflow client + Skyflow skyflowClient = Skyflow.builder() + .setLogLevel(LogLevel.ERROR) // Log level: DEBUG, INFO, WARN, ERROR, or OFF + .addVaultConfig(vaultConfig) // Add vault configuration + .build(); + + try { + // Step 4: Configure entity display options for the reidentified output. + // Entities NOT listed in any option list are reidentified to plain text by default. + + // PLAIN TEXT: Return the original sensitive value for these entities + List plainTextEntities = new ArrayList<>(); + plainTextEntities.add(DetectEntities.SSN); // Replace with entities you want in plain text + + // MASKED: Return a masked version of the value (e.g., XXX-XX-6789) + List maskedEntities = new ArrayList<>(); + maskedEntities.add(DetectEntities.CREDIT_CARD); // Replace with entities you want masked + + // REDACTED: Replace entity value with a redaction placeholder + // List redactedEntities = new ArrayList<>(); + // redactedEntities.add(DetectEntities.DOB); // Replace with entities you want redacted + + // Step 5: Build the ReidentifyTextRequest + // The `text` field should be the output of a prior deidentifyText call — + // it contains placeholder tokens like [SSN_IWdexZe] that will be resolved. + ReidentifyTextRequest reidentifyTextRequest = ReidentifyTextRequest.builder() + .text("My SSN is [SSN_IWdexZe] and my card is [CREDIT_CARD_rUzMjdQ].") // Replace with your deidentified text + .plainTextEntities(plainTextEntities) // Restore these as plain text + .maskedEntities(maskedEntities) // Restore these as masked values + // .redactedEntities(redactedEntities) // Restore these as redacted placeholders + .build(); + + // Step 6: Call reidentifyText on the vault + ReidentifyTextResponse reidentifyTextResponse = skyflowClient + .detect("") // Replace with your vault ID + .reidentifyText(reidentifyTextRequest); + + // Step 7: Print the processed text + System.out.println("Reidentify Text Response: " + reidentifyTextResponse); + + // To access the processed text string directly: + // System.out.println("Processed text: " + reidentifyTextResponse.getProcessedText()); + + } catch (SkyflowException e) { + System.err.println("Error occurred during reidentify text:"); + e.printStackTrace(); + } + } +} diff --git a/samples/src/main/java/com/example/vault/DetokenizeExample.java b/samples/src/main/java/com/example/vault/DetokenizeExample.java index ec9c37df..f8f81b31 100644 --- a/samples/src/main/java/com/example/vault/DetokenizeExample.java +++ b/samples/src/main/java/com/example/vault/DetokenizeExample.java @@ -8,6 +8,7 @@ import com.skyflow.enums.RedactionType; import com.skyflow.errors.SkyflowException; import com.skyflow.vault.tokens.DetokenizeData; +import com.skyflow.vault.tokens.DetokenizeRecordResponse; import com.skyflow.vault.tokens.DetokenizeRequest; import com.skyflow.vault.tokens.DetokenizeResponse; @@ -48,20 +49,43 @@ public static void main(String[] args) throws SkyflowException { // Step 5: Detokenize tokens from the vault try { ArrayList detokenizeData1 = new ArrayList<>(); - DetokenizeData detokenizeDataRecord1 = new DetokenizeData("", RedactionType.MASKED); // Replace with a token to detokenize with MASKED redaction - DetokenizeData detokenizeDataRecord2 = new DetokenizeData(""); // Replace with another token to detokenize with PLAIN_TEXT redaction + + // DetokenizeData accepts a token and an optional RedactionType: + // RedactionType.PLAIN_TEXT — return the full original value (default) + // RedactionType.MASKED — return a partially masked value + // RedactionType.REDACTED — return a fully redacted placeholder + // RedactionType.DEFAULT — use the vault-configured default redaction + DetokenizeData detokenizeDataRecord1 = new DetokenizeData("", RedactionType.MASKED); // MASKED redaction + DetokenizeData detokenizeDataRecord2 = new DetokenizeData("", RedactionType.PLAIN_TEXT); // PLAIN_TEXT redaction + // DetokenizeData detokenizeDataRecord3 = new DetokenizeData("", RedactionType.REDACTED); // REDACTED + // DetokenizeData detokenizeDataRecord4 = new DetokenizeData("", RedactionType.DEFAULT); // vault default detokenizeData1.add(detokenizeDataRecord1); detokenizeData1.add(detokenizeDataRecord2); DetokenizeRequest detokenizeRequest1 = DetokenizeRequest.builder() - .detokenizeData(detokenizeData1) // Specify detokenize data with specified redaction types - .continueOnError(true) // Continue processing even if an error occurs for some tokens + .detokenizeData(detokenizeData1) // Tokens to detokenize with their redaction types + .continueOnError(true) // true: return partial results on error; false: fail on first error .build(); - DetokenizeResponse detokenizeResponse1 = skyflowClient.vault().detokenize(detokenizeRequest1); // Perform detokenization - System.out.println("Detokenize Response (Vault 1): " + detokenizeResponse1); + DetokenizeResponse detokenizeResponse1 = skyflowClient.vault().detokenize(detokenizeRequest1); + + // Option A: print the full response object + System.out.println("Detokenize Response: " + detokenizeResponse1); + + // Option B: iterate DetokenizeRecordResponse to access individual fields + // for (DetokenizeRecordResponse record : detokenizeResponse1.getDetokenizedFields()) { + // System.out.println("Token : " + record.getToken()); + // System.out.println("Value : " + record.getValue()); + // System.out.println("Type : " + record.getType()); // e.g. "STRING" + // System.out.println("Request ID: " + record.getRequestId()); + // } + // for (DetokenizeRecordResponse err : detokenizeResponse1.getErrors()) { + // System.out.println("Failed token: " + err.getToken()); + // System.out.println("Error : " + err.getError()); + // } + } catch (SkyflowException e) { - System.out.println("Error during detokenization in Vault 1:"); + System.out.println("Error during detokenization:"); e.printStackTrace(); } } diff --git a/samples/src/main/java/com/example/vault/GetExample.java b/samples/src/main/java/com/example/vault/GetExample.java index 8d4cee2e..c51bd890 100644 --- a/samples/src/main/java/com/example/vault/GetExample.java +++ b/samples/src/main/java/com/example/vault/GetExample.java @@ -43,36 +43,65 @@ public static void main(String[] args) throws SkyflowException { .addSkyflowCredentials(skyflowCredentials) // Add general Skyflow credentials .build(); - // Example 1: Fetch records by Skyflow IDs from the vault + // Example 1: Fetch records by Skyflow IDs — plain text values try { ArrayList ids = new ArrayList<>(); - ids.add(""); // Replace with the Skyflow ID to fetch the record + ids.add(""); // Replace with the Skyflow ID of the record to fetch GetRequest getByIdRequest = GetRequest.builder() - .ids(ids) // Specify the list of Skyflow IDs - .table("") // Replace with the table name + .ids(ids) // Skyflow IDs to retrieve + .table("") // Replace with your table name + .redactionType(RedactionType.PLAIN_TEXT) // PLAIN_TEXT / MASKED / REDACTED / DEFAULT + .returnTokens(false) // true: return tokens instead of values + // .fields(fields) // Optional: ArrayList of column names to return (subset of columns) + // .offset("") // Optional: pagination offset (record index to start from) + // .limit("") // Optional: max number of records to return per page + // .orderBy("") // Optional: column name to sort results by + // .downloadURL(true) // Optional: return a signed download URL for file columns .build(); - GetResponse getByIdResponse = skyflowClient.vault().get(getByIdRequest); // Fetch via skyflow IDs - System.out.println("Get Response (By ID): " + getByIdResponse); + GetResponse getByIdResponse = skyflowClient.vault().get(getByIdRequest); + System.out.println("Get Response (By Skyflow ID): " + getByIdResponse); } catch (SkyflowException e) { System.out.println("Error during fetch by ID:"); e.printStackTrace(); } - // Example 2: Fetch records by column values from the vault + // Example 2: Fetch records by Skyflow IDs — return tokens instead of values + try { + ArrayList ids = new ArrayList<>(); + ids.add(""); // Replace with the Skyflow ID of the record to fetch + + GetRequest getTokensRequest = GetRequest.builder() + .ids(ids) + .table("") // Replace with your table name + .returnTokens(true) // Return vault tokens for sensitive columns instead of plain values + .build(); + + GetResponse getTokensResponse = skyflowClient.vault().get(getTokensRequest); + System.out.println("Get Response (Tokens): " + getTokensResponse); + } catch (SkyflowException e) { + System.out.println("Error during fetch tokens:"); + e.printStackTrace(); + } + + // Example 3: Fetch records by unique column values try { ArrayList columnValues = new ArrayList<>(); - columnValues.add(""); // Replace with the column value to fetch the record + columnValues.add(""); // Replace with the column value to match GetRequest getByColumnRequest = GetRequest.builder() - .table("") // Replace with the table name - .columnName("") // Replace with the column name - .columnValues(columnValues) // Specify the list of column values - .redactionType(RedactionType.PLAIN_TEXT) // Fetch the data in plain text format + .table("") // Replace with your table name + .columnName("") // Unique column to filter by (e.g. "email") + .columnValues(columnValues) // Values to match in that column + .redactionType(RedactionType.PLAIN_TEXT) // PLAIN_TEXT / MASKED / REDACTED / DEFAULT + // .fields(fields) // Optional: limit which columns are returned + // .offset("") // Optional: pagination offset + // .limit("") // Optional: max records per page + // .orderBy("") // Optional: sort column .build(); - GetResponse getByColumnResponse = skyflowClient.vault().get(getByColumnRequest); // Fetch via column values + GetResponse getByColumnResponse = skyflowClient.vault().get(getByColumnRequest); System.out.println("Get Response (By Column): " + getByColumnResponse); } catch (SkyflowException e) { System.out.println("Error during fetch by column:"); From a4c3a9fc523009f3d65a1f94a824db7eab53f00c Mon Sep 17 00:00:00 2001 From: Aadarsh Date: Wed, 3 Jun 2026 20:47:55 +0530 Subject: [PATCH 2/2] SK-2709: Added api reference doc --- README.md | 216 +++---------- docs/api_reference.md | 736 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 783 insertions(+), 169 deletions(-) create mode 100644 docs/api_reference.md diff --git a/README.md b/README.md index c446e896..96b1446c 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ The Skyflow Java SDK is designed to help with integrating Skyflow into a Java ba - [Configuration](#configuration) - [Gradle users](#gradle-users) - [Maven users](#maven-users) +- [API Reference](docs/api_reference.md) - [Migration from v1 to v2](docs/migrate_to_v2.md) - [Quickstart](#quickstart) - [Authenticate](#authenticate) @@ -69,6 +70,9 @@ The Skyflow Java SDK is designed to help with integrating Skyflow into a Java ba - Perform Vault API operations such as inserting, retrieving, and tokenizing sensitive data with ease. - Invoke connections to third-party APIs without directly handling sensitive data, ensuring compliance and data protection. +> [!TIP] +> Looking for the full list of request builder methods, response getters, enums, helper class APIs, and service-account utilities? See the **[API Reference](docs/api_reference.md)**. + # Install ## Requirements @@ -332,20 +336,20 @@ VaultController vault = skyflowClient.vault(""); | Method | Parameters | Returns | Description | |--------|-----------|---------|-------------| -| `insert(InsertRequest)` | `InsertRequest` | `InsertResponse` | Insert one or more records | -| `detokenize(DetokenizeRequest)` | `DetokenizeRequest` | `DetokenizeResponse` | Detokenize tokens to their original values | -| `tokenize(TokenizeRequest)` | `TokenizeRequest` | `TokenizeResponse` | Tokenize sensitive values | -| `get(GetRequest)` | `GetRequest` | `GetResponse` | Retrieve records by Skyflow ID or column value | -| `update(UpdateRequest)` | `UpdateRequest` | `UpdateResponse` | Update a record by Skyflow ID | -| `delete(DeleteRequest)` | `DeleteRequest` | `DeleteResponse` | Delete records by Skyflow ID | -| `query(QueryRequest)` | `QueryRequest` | `QueryResponse` | Execute a SQL query | -| `uploadFile(FileUploadRequest)` | `FileUploadRequest` | `FileUploadResponse` | Upload a file to a vault column | +| `insert(InsertRequest)` | [`InsertRequest`](docs/api_reference.md#insertrequest) | [`InsertResponse`](docs/api_reference.md#insertresponse) | Insert one or more records | +| `detokenize(DetokenizeRequest)` | [`DetokenizeRequest`](docs/api_reference.md#detokenizerequest) | [`DetokenizeResponse`](docs/api_reference.md#detokenizeresponse) | Detokenize tokens to their original values | +| `tokenize(TokenizeRequest)` | [`TokenizeRequest`](docs/api_reference.md#tokenizerequest) | [`TokenizeResponse`](docs/api_reference.md#tokenizeresponse) | Tokenize sensitive values | +| `get(GetRequest)` | [`GetRequest`](docs/api_reference.md#getrequest) | [`GetResponse`](docs/api_reference.md#getresponse) | Retrieve records by Skyflow ID or column value | +| `update(UpdateRequest)` | [`UpdateRequest`](docs/api_reference.md#updaterequest) | [`UpdateResponse`](docs/api_reference.md#updateresponse) | Update a record by Skyflow ID | +| `delete(DeleteRequest)` | [`DeleteRequest`](docs/api_reference.md#deleterequest) | [`DeleteResponse`](docs/api_reference.md#deleteresponse) | Delete records by Skyflow ID | +| `query(QueryRequest)` | [`QueryRequest`](docs/api_reference.md#queryrequest) | [`QueryResponse`](docs/api_reference.md#queryresponse) | Execute a SQL query | +| `uploadFile(FileUploadRequest)` | [`FileUploadRequest`](docs/api_reference.md#fileuploadrequest) | [`FileUploadResponse`](docs/api_reference.md#fileuploadresponse) | Upload a file to a vault column | All methods throw `SkyflowException` on error. ## Insert data into the vault -Apart from using the `insert` method to insert data into your vault covered in [Quickstart](#quickstart), you can also specify options in `InsertRequest`, such as returning tokenized data, upserting records, or continuing the operation in case of errors. +Apart from using the `insert` method to insert data into your vault covered in [Quickstart](#quickstart), you can also specify options in [`InsertRequest`](docs/api_reference.md#insertrequest), such as returning tokenized data, upserting records, or continuing the operation in case of errors. Returns an [`InsertResponse`](docs/api_reference.md#insertresponse). ### Construct an insert request @@ -565,24 +569,12 @@ Skyflow returns tokens, with `upsert` support, for the record you just inserted. ## Detokenize -To retrieve tokens from your vault, use the `detokenize` method. The `DetokenizeRequest` class requires a list of detokenization data as input. Additionally, you can provide optional parameters, such as the redaction type and the option to continue on error. - -### DetokenizeData - -Each entry in the detokenize list is a `DetokenizeData` object pairing a token with its desired redaction type. - -| Constructor | Description | -|-------------|-------------| -| `new DetokenizeData(String token)` | Detokenize with default redaction (`RedactionType.DEFAULT`) | -| `new DetokenizeData(String token, RedactionType redactionType)` | Detokenize with a specific redaction type | - -| Method | Return type | Description | -|--------|------------|-------------| -| `getToken()` | `String` | The token value | -| `getRedactionType()` | `RedactionType` | The redaction type applied to the result | +To retrieve tokens from your vault, use the `detokenize` method. [`DetokenizeRequest`](docs/api_reference.md#detokenizerequest) requires a list of detokenization data as input. Returns a [`DetokenizeResponse`](docs/api_reference.md#detokenizeresponse). ### Construct a detokenize request +Each entry in the detokenize list is a [`DetokenizeData`](docs/api_reference.md#detokenizedata) object pairing a token with its desired redaction type. See the [API Reference](docs/api_reference.md#detokenizerequest) for all `DetokenizeRequest` builder options. + ```java import com.skyflow.enums.RedactionType; import com.skyflow.errors.SkyflowException; @@ -721,15 +713,7 @@ for (DetokenizeRecordResponse err : detokenizeResponse.getErrors()) { } ``` -**`DetokenizeRecordResponse` methods:** - -| Method | Return type | Description | -|--------|------------|-------------| -| `getToken()` | `String` | The original token value | -| `getValue()` | `String` | The detokenized (plaintext) value; `null` on error | -| `getType()` | `String` | Data type of the value (e.g. `"STRING"`); `null` if not set | -| `getError()` | `String` | Error message when detokenization failed; `null` on success | -| `getRequestId()` | `String` | The `x-request-id` for the underlying API call | +See [`DetokenizeRecordResponse`](docs/api_reference.md#detokenizerecordresponse) in the API Reference for the full attribute list. ### An example of a detokenize call with `continueOnError` option: @@ -809,31 +793,12 @@ Sample response: Tokenization replaces sensitive data with unique identifier tokens. This approach protects sensitive information by securely storing the original data while allowing the use of tokens within your application. -To tokenize data, use the `tokenize` method. The `TokenizeRequest` class creates a tokenize request. In this request, you specify the `values` parameter, which is a list of `ColumnValue` objects. Each `ColumnValue` contains two properties: `value` and `columnGroup`. - -### ColumnValue - -`ColumnValue` pairs a sensitive value with the column group that defines how it is tokenized. - -```java -ColumnValue columnValue = ColumnValue.builder() - .value("") // the data to tokenize - .columnGroup("") // the vault column group name - .build(); -``` - -| Builder method | Description | -|---------------|-------------| -| `.value(String)` | The sensitive value to tokenize | -| `.columnGroup(String)` | The column group in the vault that defines the tokenization policy | - -| Getter | Return type | Description | -|--------|------------|-------------| -| `getValue()` | `String` | The original value | -| `getColumnGroup()` | `String` | The column group name | +To tokenize data, use the `tokenize` method. [`TokenizeRequest`](docs/api_reference.md#tokenizerequest) accepts a list of [`ColumnValue`](docs/api_reference.md#columnvalue) objects. Returns a [`TokenizeResponse`](docs/api_reference.md#tokenizeresponse). ### Construct a tokenize request +Each entry in the tokenize list is a [`ColumnValue`](docs/api_reference.md#columnvalue) object pairing a value with its column group. See the [API Reference](docs/api_reference.md#tokenizerequest) for all `TokenizeRequest` builder options. + ```java import com.skyflow.errors.SkyflowException; import com.skyflow.vault.tokens.ColumnValue; @@ -942,7 +907,7 @@ Sample response: ## Get -To retrieve data using Skyflow IDs or unique column values, use the `get` method. The `GetRequest` class creates a get request, where you specify parameters such as the table name, redaction type, Skyflow IDs, column names, column values, and whether to return tokens. If you specify Skyflow IDs, you can't use column names and column values, and the inverse is true—if you specify column names and column values, you can't use Skyflow IDs. +To retrieve data using Skyflow IDs or unique column values, use the `get` method. [`GetRequest`](docs/api_reference.md#getrequest) accepts parameters such as table name, redaction type, Skyflow IDs, column names, and column values. `ids` and `columnName`/`columnValues` are mutually exclusive. Returns a [`GetResponse`](docs/api_reference.md#getresponse). ### Construct a get request @@ -1256,27 +1221,11 @@ Sample response: ### Redaction types -Redaction types determine how sensitive data is displayed when retrieved from the vault. - -#### **Available Redaction Types** - -- `DEFAULT`: Applies the vault-configured default redaction setting. -- `REDACTED`: Completely removes sensitive data from view. -- `MASKED`: Partially obscures sensitive information. -- `PLAIN_TEXT`: Displays the full, unmasked data. - -#### **Choosing the Right Redaction Type** - -- Use `REDACTED` for scenarios requiring maximum data protection to prevent exposure of sensitive information. -- Use `MASKED` to provide partial visibility of sensitive data for less critical use cases. -- Use `PLAIN_TEXT` for internal, authorized access where full data visibility is necessary. +See [`RedactionType`](docs/api_reference.md#redactiontype) in the API Reference for all available values and their descriptions. ## Update -To update data in your vault, use the `update` method. The `UpdateRequest` class is used to create an update request, -where you specify parameters such as the table name, data (as a map of key value pairs), tokens, returnTokens, and -tokenStrict. If `returnTokens` is set to `true`, Skyflow returns tokens for the updated records. If `returnTokens` is -set to `false`, Skyflow returns IDs for the updated records. +To update data in your vault, use the `update` method. [`UpdateRequest`](docs/api_reference.md#updaterequest) accepts the table name, data map, optional tokens, `returnTokens`, and `tokenMode`. Returns an [`UpdateResponse`](docs/api_reference.md#updateresponse) with the `skyflow_id` and (when `returnTokens=true`) a token per updated column. ### Construct an update request @@ -1409,8 +1358,7 @@ Sample response: ## Delete -To delete records using Skyflow IDs, use the `delete` method. The `DeleteRequest` class accepts a list of Skyflow IDs -that you want to delete, as shown below: +To delete records using Skyflow IDs, use the `delete` method. [`DeleteRequest`](docs/api_reference.md#deleterequest) accepts a table name and list of Skyflow IDs. Returns a [`DeleteResponse`](docs/api_reference.md#deleteresponse). ### Construct a delete request @@ -1518,7 +1466,7 @@ Sample response: ## Query -To retrieve data with SQL queries, use the `query` method. The `QueryRequest` class accepts a `query` parameter, as shown below. +To retrieve data with SQL queries, use the `query` method. [`QueryRequest`](docs/api_reference.md#queryrequest) accepts a `query` string. Returns a [`QueryResponse`](docs/api_reference.md#queryresponse). ### Construct a query request @@ -1619,7 +1567,7 @@ Sample response: ## Upload File -To upload files to a Skyflow vault, use the `uploadFile` method. The `UploadFileRequest` class accepts parameters such as the file path, table name, and file name. +To upload files to a Skyflow vault, use the `uploadFile` method. [`FileUploadRequest`](docs/api_reference.md#fileuploadrequest) accepts the table name, column name, optional skyflow ID, and a file source (`fileObject`, `filePath`, or `base64`). Returns a [`FileUploadResponse`](docs/api_reference.md#fileuploadresponse). ### Construct a file upload request @@ -1730,13 +1678,13 @@ DetectController detect = skyflowClient.detect(""); | Method | Parameters | Returns | Description | |--------|-----------|---------|-------------| -| `deidentifyText(DeidentifyTextRequest)` | `DeidentifyTextRequest` | `DeidentifyTextResponse` | Deidentify sensitive entities in text | -| `reidentifyText(ReidentifyTextRequest)` | `ReidentifyTextRequest` | `ReidentifyTextResponse` | Restore original values from a deidentified text | -| `deidentifyFile(DeidentifyFileRequest)` | `DeidentifyFileRequest` | `DeidentifyFileResponse` | Deidentify sensitive data in a file | -| `getDetectRun(GetDetectRunRequest)` | `GetDetectRunRequest` | `DeidentifyFileResponse` | Poll for the result of an async file deidentification | +| `deidentifyText(DeidentifyTextRequest)` | [`DeidentifyTextRequest`](docs/api_reference.md#deidentifytextrequest) | [`DeidentifyTextResponse`](docs/api_reference.md#deidentifytextresponse) | Deidentify sensitive entities in text | +| `reidentifyText(ReidentifyTextRequest)` | [`ReidentifyTextRequest`](docs/api_reference.md#reidentifytextrequest) | [`ReidentifyTextResponse`](docs/api_reference.md#reidentifytextresponse) | Restore original values from a deidentified text | +| `deidentifyFile(DeidentifyFileRequest)` | [`DeidentifyFileRequest`](docs/api_reference.md#deidentifyfilerequest) | [`DeidentifyFileResponse`](docs/api_reference.md#deidentifyfileresponse) | Deidentify sensitive data in a file | +| `getDetectRun(GetDetectRunRequest)` | [`GetDetectRunRequest`](docs/api_reference.md#getdetectrunrequest) | [`DeidentifyFileResponse`](docs/api_reference.md#deidentifyfileresponse) | Poll for the result of an async file deidentification | ## Deidentify Text -To deidentify text, use the `deidentifyText` method. The `DeidentifyTextRequest` class creates a deidentify text request, which includes the text to be deidentified. Additionally, you can provide optional parameters using the `DeidentifyTextOptions` class. +To deidentify text, use the `deidentifyText` method. [`DeidentifyTextRequest`](docs/api_reference.md#deidentifytextrequest) accepts the text to deidentify along with optional entity types, regex lists, token format, and transformations. Returns a [`DeidentifyTextResponse`](docs/api_reference.md#deidentifytextresponse). ### Construct an deidentify text request @@ -1939,7 +1887,7 @@ Sample Response: ``` ## Reidentify Text -To reidentify text, use the `reidentifyText` method. The `ReidentifyTextRequest` class creates a reidentify text request, which includes the redacted or deidentified text to be reidentified. Additionally, you can provide optional parameters using the ReidentifyTextOptions class to control how specific entities are returned (as redacted, masked, or plain text). +To reidentify text, use the `reidentifyText` method. [`ReidentifyTextRequest`](docs/api_reference.md#reidentifytextrequest) accepts the redacted/deidentified text and optional entity lists controlling which entities to reveal, mask, or keep redacted. Returns a [`ReidentifyTextResponse`](docs/api_reference.md#reidentifytextresponse). ### Construct an reidentify text request @@ -2048,11 +1996,11 @@ Sample Response: ``` ## Deidentify file -To deidentify files, use the `deidentifyFile` method. The `DeidentifyFileRequest` class creates a deidentify file request, which includes the file to be deidentified (such as images, PDFs, audio, documents, spreadsheets, or presentations). Additionally, you can provide optional parameters using the DeidentifyFileOptions class to control how entities are detected and deidentified, as well as how the output is generated for different file types. +To deidentify files, use the `deidentifyFile` method. [`DeidentifyFileRequest`](docs/api_reference.md#deidentifyfilerequest) accepts a [`FileInput`](docs/api_reference.md#fileinput) and optional parameters controlling entity detection, masking, output format, and async wait time. Supports images, PDFs, audio, documents, spreadsheets, and presentations. Returns a [`DeidentifyFileResponse`](docs/api_reference.md#deidentifyfileresponse). ### AudioBleep -`AudioBleep` controls how detected sensitive audio segments are replaced with a bleep tone. Used in `DeidentifyFileRequest.builder().bleep(audioBleep)` for audio files. +[`AudioBleep`](docs/api_reference.md#audiobleep) controls how detected sensitive audio segments are replaced with a bleep tone. Used in `DeidentifyFileRequest.builder().bleep(audioBleep)` for audio files. ```java import com.skyflow.vault.detect.AudioBleep; @@ -2065,13 +2013,6 @@ AudioBleep audioBleep = AudioBleep.builder() .build(); ``` -| Builder method | Type | Description | -|---------------|------|-------------| -| `.frequency(Double)` | `Double` | Tone frequency in Hz | -| `.gain(Double)` | `Double` | Tone gain (volume) | -| `.startPadding(Double)` | `Double` | Padding before the bleep in seconds | -| `.stopPadding(Double)` | `Double` | Padding after the bleep in seconds | - ### Construct an deidentify file request ```java @@ -2297,9 +2238,7 @@ Sample response (when the API takes more than 64 seconds): ``` ## Get run: -To retrieve the results of a previously started file `deidentification operation`, use the `getDetectRun` method. -The `GetDetectRunRequest` class is initialized with the `runId` returned from a prior deidentifyFile call. -This method allows you to fetch the final results of the file processing operation once they are available. +To retrieve the results of a previously started file deidentification operation, use the `getDetectRun` method. [`GetDetectRunRequest`](docs/api_reference.md#getdetectrunrequest) accepts the `runId` returned from a prior `deidentifyFile` call. Returns a [`DeidentifyFileResponse`](docs/api_reference.md#deidentifyfileresponse). ### Construct an get run request @@ -2403,31 +2342,11 @@ Sample Response: ## Detect response types -The Detect API returns structured objects for detected entities. These types appear in `DeidentifyTextResponse.getEntities()` and `DeidentifyFileResponse.getEntities()`. - -### EntityInfo - -Represents a single detected entity in a text deidentification response. +The Detect API returns structured objects for detected entities. See the API Reference for full attribute lists: [`EntityInfo`](docs/api_reference.md#entityinfo), [`TextIndex`](docs/api_reference.md#textindex), [`FileEntityInfo`](docs/api_reference.md#fileentityinfo), [`FileInfo`](docs/api_reference.md#fileinfo). -| Method | Return type | Description | -|--------|------------|-------------| -| `getToken()` | `String` | Placeholder token that replaced the entity in the processed text | -| `getValue()` | `String` | Original sensitive value that was detected | -| `getEntity()` | `String` | Entity type label (e.g. `"SSN"`, `"CREDIT_CARD"`) | -| `getTextIndex()` | `TextIndex` | Character positions of the entity in the **original** text | -| `getProcessedIndex()` | `TextIndex` | Character positions of the token in the **processed** text | -| `getScores()` | `Map` | Confidence scores per entity type (e.g. `{"SSN": 0.93}`) | +### EntityInfo and TextIndex -### TextIndex - -Represents the start and end character positions of a detected entity. - -| Method | Return type | Description | -|--------|------------|-------------| -| `getStart()` | `int` | Inclusive start character index | -| `getEnd()` | `int` | Exclusive end character index | - -**Example:** +[`EntityInfo`](docs/api_reference.md#entityinfo) appears in `DeidentifyTextResponse.getEntities()`. Each entry includes the detected entity type, original value, replacement token, character positions ([`TextIndex`](docs/api_reference.md#textindex)), and confidence scores. ```java DeidentifyTextResponse response = skyflowClient.detect("").deidentifyText(request); @@ -2442,38 +2361,17 @@ for (EntityInfo entity : response.getEntities()) { } ``` -### FileEntityInfo - -Appears inside `DeidentifyFileResponse.getEntities()` — represents a detected-entity output file (e.g. a JSON file listing all found entities). +### FileEntityInfo and FileInfo -| Method | Return type | Description | -|--------|------------|-------------| -| `getFile()` | `String` | Base64-encoded content of the entity output file | -| `getType()` | `String` | Output type (e.g. `"entities"`) | -| `getExtension()` | `String` | File extension of the output (e.g. `"json"`) | - -### FileInfo - -Wraps metadata about a file used in detect operations. - -| Method | Return type | Description | -|--------|------------|-------------| -| `getName()` | `String` | File name | -| `getSize()` | `long` | File size in bytes | -| `getType()` | `String` | MIME type (may be empty for some formats) | -| `getLastModified()` | `long` | Last modified timestamp (milliseconds since epoch) | +[`FileEntityInfo`](docs/api_reference.md#fileentityinfo) appears in `DeidentifyFileResponse.getEntities()`. [`FileInfo`](docs/api_reference.md#fileinfo) is returned by `DeidentifyFileResponse.getFile()` and contains file metadata. ## Detect enums -### TokenType +See the API Reference for full value descriptions: [`TokenType`](docs/api_reference.md#tokentype), [`DeidentifyFileStatus`](docs/api_reference.md#deidentifyfilestatus), [`DetectOutputTranscriptions`](docs/api_reference.md#detectoutputtranscriptions), [`MaskingMethod`](docs/api_reference.md#maskingmethod), [`DetectEntities`](docs/api_reference.md#detectentities). -Controls how detected entities are tokenized in the output. Used in `TokenFormat.builder()`. +### TokenType -| Value | Description | -|-------|-------------| -| `VAULT_TOKEN` | Store the entity in the vault and return a vault token | -| `ENTITY_UNIQUE_COUNTER` | Return a deterministic label with a counter suffix (default) | -| `ENTITY_ONLY` | Return only the entity label, without a counter | +[`TokenType`](docs/api_reference.md#tokentype) controls how detected entities are tokenized. Used in `TokenFormat.builder()`. ```java import com.skyflow.enums.TokenType; @@ -2487,14 +2385,7 @@ TokenFormat tokenFormat = TokenFormat.builder() ### DeidentifyFileStatus -Returned in `DeidentifyFileResponse.getStatus()` to indicate the processing state of an async deidentify-file operation. - -| Value | Description | -|-------|-------------| -| `IN_PROGRESS` | File is still being processed | -| `SUCCESS` | Processing completed successfully | -| `FAILED` | Processing failed | -| `UNKNOWN` | Status could not be determined | +[`DeidentifyFileStatus`](docs/api_reference.md#deidentifyfilestatus) is returned in `DeidentifyFileResponse.getStatus()` to indicate async processing state. ```java import com.skyflow.enums.DeidentifyFileStatus; @@ -2509,14 +2400,7 @@ if (DeidentifyFileStatus.SUCCESS.value().equals(response.getStatus())) { ### DetectOutputTranscriptions -Controls the transcription format for audio file deidentification. Used in `DeidentifyFileRequest.builder().outputTranscription(DetectOutputTranscriptions)`. - -| Value | Description | -|-------|-------------| -| `TRANSCRIPTION` | Standard transcription of the audio | -| `DIARIZED_TRANSCRIPTION` | Transcription with speaker labels | -| `MEDICAL_TRANSCRIPTION` | Medical-domain transcription | -| `MEDICAL_DIARIZED_TRANSCRIPTION` | Medical-domain transcription with speaker labels | +[`DetectOutputTranscriptions`](docs/api_reference.md#detectoutputtranscriptions) controls the transcription format for audio file deidentification. ```java import com.skyflow.enums.DetectOutputTranscriptions; @@ -2550,7 +2434,7 @@ ConnectionController connection = skyflowClient.connection(""); | Method | Parameters | Returns | Description | |--------|-----------|---------|-------------| -| `invoke(InvokeConnectionRequest)` | `InvokeConnectionRequest` | `InvokeConnectionResponse` | Invoke an inbound or outbound connection | +| `invoke(InvokeConnectionRequest)` | [`InvokeConnectionRequest`](docs/api_reference.md#invokeconnectionrequest) | [`InvokeConnectionResponse`](docs/api_reference.md#invokeconnectionresponse) | Invoke an inbound or outbound connection | ## Invoke a connection @@ -2625,13 +2509,7 @@ public class InvokeConnectionSchema { } ``` -`method` supports the following methods: - -- GET -- POST -- PUT -- PATCH -- DELETE +`method` accepts any [`RequestMethod`](docs/api_reference.md#requestmethod) value (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). See [`InvokeConnectionRequest`](docs/api_reference.md#invokeconnectionrequest) in the API Reference for all builder options. **pathParams, queryParams, requestHeader, requestBody** are the JSON objects represented as HashMaps, that will be sent through the connection integration url. diff --git a/docs/api_reference.md b/docs/api_reference.md new file mode 100644 index 00000000..8f5716a5 --- /dev/null +++ b/docs/api_reference.md @@ -0,0 +1,736 @@ +# API Reference + +A reference for the public Skyflow Java SDK surface: client-management methods, config classes, request and response objects, helper classes, enums, and service-account utilities. For task-oriented usage and examples, see the [README](../README.md). + +All attributes, parameters, and enum values below are taken directly from the SDK source. + +## Table of Contents + +- [Client management methods](#client-management-methods) +- [Config classes](#config-classes) +- [Request objects](#request-objects) +- [Response objects](#response-objects) +- [Helper classes](#helper-classes) +- [Enums](#enums) +- [Service account utilities](#service-account-utilities) + +--- + +## Client management methods + +A built `Skyflow` client exposes methods to mutate its configuration and logging at runtime, in addition to the builder methods used during initialization. + +### Builder methods (`Skyflow.builder()`) + +| Method | Returns | Description | +|--------|---------|-------------| +| `addVaultConfig(VaultConfig)` | `SkyflowClientBuilder` | Add a vault configuration. | +| `updateVaultConfig(VaultConfig)` | `SkyflowClientBuilder` | Replace an existing vault configuration (matched by `vaultId`). | +| `removeVaultConfig(String vaultId)` | `SkyflowClientBuilder` | Remove a vault configuration. | +| `addConnectionConfig(ConnectionConfig)` | `SkyflowClientBuilder` | Add a connection configuration. | +| `updateConnectionConfig(ConnectionConfig)` | `SkyflowClientBuilder` | Replace an existing connection configuration. | +| `removeConnectionConfig(String connectionId)` | `SkyflowClientBuilder` | Remove a connection configuration. | +| `addSkyflowCredentials(Credentials)` | `SkyflowClientBuilder` | Set client-level credentials applied when a vault or connection config does not specify its own. | +| `setLogLevel(LogLevel)` | `SkyflowClientBuilder` | Set the log level. See [`LogLevel`](#loglevel). | +| `build()` | `Skyflow` | Build and return the `Skyflow` client. | + +### Instance methods (built `Skyflow` client) + +| Method | Returns | Description | +|--------|---------|-------------| +| `addVaultConfig(VaultConfig)` | `Skyflow` | Add a vault configuration after build. | +| `getVaultConfig(String vaultId)` | `VaultConfig` | Retrieve a vault configuration by ID. | +| `updateVaultConfig(VaultConfig)` | `Skyflow` | Replace a vault configuration (matched by `vaultId`). | +| `removeVaultConfig(String vaultId)` | `Skyflow` | Remove a vault configuration. | +| `addConnectionConfig(ConnectionConfig)` | `Skyflow` | Add a connection configuration. | +| `getConnectionConfig(String connectionId)` | `ConnectionConfig` | Retrieve a connection configuration by ID. | +| `updateConnectionConfig(ConnectionConfig)` | `Skyflow` | Replace a connection configuration. | +| `removeConnectionConfig(String connectionId)` | `Skyflow` | Remove a connection configuration. | +| `updateSkyflowCredentials(Credentials)` | `Skyflow` | Replace the client-level credentials. | +| `updateLogLevel(LogLevel)` | `Skyflow` | Change the log level after initialization. | +| `getLogLevel()` | `LogLevel` | Return the current log level. | +| `vault()` | `VaultController` | Get a controller for the first (or only) vault. | +| `vault(String vaultId)` | `VaultController` | Get a controller for the specified vault. | +| `connection()` | `ConnectionController` | Get a controller for the first (or only) connection. | +| `connection(String connectionId)` | `ConnectionController` | Get a controller for the specified connection. | +| `detect()` | `DetectController` | Get a Detect controller for the first (or only) vault. | +| `detect(String vaultId)` | `DetectController` | Get a Detect controller for the specified vault. | + +All mutating instance methods return the `Skyflow` instance for chaining and throw `SkyflowException` on validation errors. + +```java +// Example: manage configuration after the client is built +skyflowClient.addVaultConfig(anotherVaultConfig); +skyflowClient.updateLogLevel(LogLevel.DEBUG); +LogLevel currentLevel = skyflowClient.getLogLevel(); +``` + +--- + +## Config classes + +### `VaultConfig` + +`com.skyflow.config` — passed to `addVaultConfig()` / `updateVaultConfig()`. + +| Setter | Getter | Type | Description | +|--------|--------|------|-------------| +| `setVaultId(String)` | `getVaultId()` | `String` | _(required)_ Vault ID. | +| `setClusterId(String)` | `getClusterId()` | `String` | _(required)_ Cluster ID (first segment of the vault URL). | +| `setEnv(Env)` | `getEnv()` | `Env` | Deployment environment. Default: `Env.PROD`. See [`Env`](#env). | +| `setCredentials(Credentials)` | `getCredentials()` | `Credentials` | Vault-specific credentials. Overrides client-level credentials for this vault. | + +### `ConnectionConfig` + +`com.skyflow.config` — passed to `addConnectionConfig()` / `updateConnectionConfig()`. + +| Setter | Getter | Type | Description | +|--------|--------|------|-------------| +| `setConnectionId(String)` | `getConnectionId()` | `String` | _(required)_ Connection ID. | +| `setConnectionUrl(String)` | `getConnectionUrl()` | `String` | _(required)_ Connection URL. | +| `setCredentials(Credentials)` | `getCredentials()` | `Credentials` | Connection-specific credentials. Overrides client-level credentials for this connection. | + +### `Credentials` + +`com.skyflow.config` — use exactly one of the authentication fields; the last one set takes precedence. + +| Setter | Getter | Type | Description | +|--------|--------|------|-------------| +| `setApiKey(String)` | `getApiKey()` | `String` | API key for direct authentication. | +| `setToken(String)` | `getToken()` | `String` | Static bearer token. | +| `setPath(String)` | `getPath()` | `String` | Path to a service account `credentials.json` file. | +| `setCredentialsString(String)` | `getCredentialsString()` | `String` | Service account credentials as a JSON string. | +| `setRoles(ArrayList)` | `getRoles()` | `ArrayList` | Role IDs to scope the generated bearer token. | +| `setContext(String)` | `getContext()` | `Object` | String context embedded in the bearer token for context-aware authorization. | +| `setContext(Map)` | `getContext()` | `Object` | Map context embedded in the bearer token. Keys must match `[a-zA-Z0-9_]`. | + +--- + +## Request objects + +Parameters listed with their defaults as defined in the builders. + +### `InsertRequest` + +`com.skyflow.vault.data` — passed to `vault().insert()`. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `table(String)` | _(required)_ | Target table name. | +| `values(ArrayList>)` | _(required)_ | List of records to insert. Each record is a `field → value` map. | +| `tokens(ArrayList>)` | `null` | Bring-your-own-token values aligned with `values` (used with `tokenMode`). | +| `returnTokens(Boolean)` | `false` | Return tokens for inserted values. | +| `upsert(String)` | `null` | Column name to use as the upsert index (must have a `unique` constraint). | +| `homogeneous(Boolean)` | `false` | Treat the batch as homogeneous (all records share the same columns). | +| `continueOnError(Boolean)` | `false` | Continue the batch despite partial errors. | +| `tokenMode(TokenMode)` | `TokenMode.DISABLE` | BYOT mode. See [`TokenMode`](#tokenmode). | + +### `GetRequest` + +`com.skyflow.vault.data` — passed to `vault().get()`. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `table(String)` | _(required)_ | Target table name. | +| `ids(ArrayList)` | `null` | Skyflow IDs to retrieve. Mutually exclusive with `columnName`/`columnValues`. | +| `redactionType(RedactionType)` | `null` | See [`RedactionType`](#redactiontype). | +| `returnTokens(Boolean)` | `false` | Return tokens instead of values. | +| `fields(ArrayList)` | `null` | Specific fields/columns to return. | +| `offset(String)` | `null` | Pagination offset. | +| `limit(String)` | `null` | Pagination limit. | +| `downloadUrl(Boolean)` | `true` | Return file download URLs for file columns. | +| `columnName(String)` | `null` | Unique column to look up by. Mutually exclusive with `ids`. | +| `columnValues(ArrayList)` | `null` | Values for `columnName`. | +| `orderBy(String)` | `"ASC"` | Sort order for results. | + +### `UpdateRequest` + +`com.skyflow.vault.data` — passed to `vault().update()`. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `table(String)` | _(required)_ | Target table name. | +| `data(HashMap)` | _(required)_ | Map containing `skyflow_id` and the columns to update. | +| `tokens(HashMap)` | `null` | BYOT values for the updated columns. | +| `returnTokens(Boolean)` | `false` | Return tokens (vs. IDs) for updated record. | +| `tokenMode(TokenMode)` | `TokenMode.DISABLE` | BYOT mode. See [`TokenMode`](#tokenmode). | + +### `DeleteRequest` + +`com.skyflow.vault.data` — passed to `vault().delete()`. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `table(String)` | _(required)_ | Target table name. | +| `ids(ArrayList)` | _(required)_ | List of Skyflow IDs to delete. | + +### `QueryRequest` + +`com.skyflow.vault.data` — passed to `vault().query()`. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `query(String)` | _(required)_ | SQL query string to execute. | + +### `FileUploadRequest` + +`com.skyflow.vault.data` — passed to `vault().uploadFile()`. Provide exactly one file source: `fileObject`, `filePath`, or `base64`. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `table(String)` | _(required)_ | Target table name. | +| `columnName(String)` | `null` | File column name. | +| `skyflowId(String)` | `null` | Existing record ID. Omit to create a new record. | +| `filePath(String)` | `null` | Path to a file to upload. | +| `base64(String)` | `null` | Base64-encoded file content. | +| `fileObject(File)` | `null` | A `java.io.File` object to upload. | +| `fileName(String)` | `null` | Override the file name sent to the vault. | + +### `DetokenizeRequest` + +`com.skyflow.vault.tokens` — passed to `vault().detokenize()`. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `detokenizeData(ArrayList)` | _(required)_ | List of [`DetokenizeData`](#detokenizedata) objects pairing tokens with redaction types. | +| `continueOnError(Boolean)` | `false` | Continue despite per-token errors. | +| `downloadUrl(Boolean)` | `false` | Return file download URLs for file-type tokens. | + +### `TokenizeRequest` + +`com.skyflow.vault.tokens` — passed to `vault().tokenize()`. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `values(List)` | _(required)_ | List of [`ColumnValue`](#columnvalue) objects to tokenize. | + +### `DeidentifyTextRequest` + +`com.skyflow.vault.detect` — passed to `detect().deidentifyText()`. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `text(String)` | _(required)_ | Text to de-identify. | +| `entities(List)` | `null` | Entity types to detect. See [`DetectEntities`](#detectentities). | +| `allowRegexList(List)` | `null` | Regex patterns to always treat as detectable. | +| `restrictRegexList(List)` | `null` | Regex patterns to exclude from detection. | +| `tokenFormat(TokenFormat)` | `null` | Token format controlling token types per entity. See [`TokenFormat`](#tokenformat). | +| `transformations(Transformations)` | `null` | Data transformations (e.g. date shifting). See [`Transformations`](#transformations). | + +### `ReidentifyTextRequest` + +`com.skyflow.vault.detect` — passed to `detect().reidentifyText()`. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `text(String)` | _(required)_ | The redacted/de-identified text to re-identify. | +| `redactedEntities(List)` | `null` | Entity types to keep redacted. | +| `maskedEntities(List)` | `null` | Entity types to mask. | +| `plainTextEntities(List)` | `null` | Entity types to reveal as plain text. | + +### `DeidentifyFileRequest` + +`com.skyflow.vault.detect` — passed to `detect().deidentifyFile()`. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `file(FileInput)` | _(required)_ | File source. See [`FileInput`](#fileinput). | +| `entities(List)` | `null` | Entity types to detect. | +| `allowRegexList(List)` | `null` | Regex patterns to always treat as detectable. | +| `restrictRegexList(List)` | `null` | Regex patterns to exclude. | +| `tokenFormat(TokenFormat)` | `null` | Token format per entity. | +| `transformations(Transformations)` | `null` | Transformations (not supported for Documents/Images/PDFs). | +| `outputProcessedImage(Boolean)` | `false` | Include the processed image in the response. | +| `outputOcrText(Boolean)` | `false` | Include OCR text in the response. | +| `maskingMethod(MaskingMethod)` | `null` | See [`MaskingMethod`](#maskingmethod). | +| `pixelDensity(Number)` | `null` | Pixel density for PDF processing. | +| `maxResolution(Number)` | `null` | Max resolution for PDF processing. | +| `outputProcessedAudio(Boolean)` | `false` | Include processed audio in the response. | +| `outputTranscription(DetectOutputTranscriptions)` | `null` | See [`DetectOutputTranscriptions`](#detectoutputtranscriptions). | +| `bleep(AudioBleep)` | `null` | Audio bleep configuration. See [`AudioBleep`](#audiobleep). | +| `outputDirectory(String)` | `null` | Directory to write the processed file. | +| `waitTime(Integer)` | `null` | Max seconds to wait for async file processing (≤ 64). | + +### `GetDetectRunRequest` + +`com.skyflow.vault.detect` — passed to `detect().getDetectRun()`. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `runId(String)` | _(required)_ | The `run_id` returned by a prior `deidentifyFile` call. | + +### `InvokeConnectionRequest` + +`com.skyflow.vault.connection` — passed to `connection().invoke()`. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `method(RequestMethod)` | `RequestMethod.POST` | HTTP method. See [`RequestMethod`](#requestmethod). | +| `pathParams(Map)` | `null` | Path parameters. | +| `queryParams(Map)` | `null` | Query parameters. | +| `requestHeaders(Map)` | `null` | Request headers. | +| `requestBody(Object)` | `null` | Request body. | + +--- + +## Response objects + +Every vault, token, connection, and Detect operation returns a typed response object. Each attribute below lists its type and meaning. + +> **The `errors` attribute** is common to most responses. It is populated only on partial failure (for example when `continueOnError=true`); it is `null` (or empty) when there are no errors. + +All response classes serialize to JSON via `toString()`. + +### `InsertResponse` + +`com.skyflow.vault.data` — returned by `vault().insert()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getInsertedFields()` | `ArrayList>` | One entry per inserted record. Each map contains `skyflow_id`; with `returnTokens=true`, also a token per column; with `continueOnError=true`, also a `request_index`. | +| `getErrors()` | `ArrayList>` | Per-record errors when `continueOnError=true`. Each map contains `request_index`, `request_id`, `error`, and `http_code`. | + +### `GetResponse` + +`com.skyflow.vault.data` — returned by `vault().get()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getData()` | `ArrayList>` | Retrieved records as `field → value` maps (tokens instead of values when `returnTokens=true`). | +| `getErrors()` | `ArrayList>` | Errors when `continueOnError=true`. | + +### `UpdateResponse` + +`com.skyflow.vault.data` — returned by `vault().update()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getSkyflowId()` | `String` | The Skyflow ID of the updated record. | +| `getTokens()` | `HashMap` | A token per updated column when `returnTokens=true`. | + +### `DeleteResponse` + +`com.skyflow.vault.data` — returned by `vault().delete()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getDeletedIds()` | `List` | Skyflow IDs of the deleted records. | + +### `QueryResponse` + +`com.skyflow.vault.data` — returned by `vault().query()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getFields()` | `ArrayList>` | Matching records. Each record map also includes a `tokenized_data` entry. | +| `getErrors()` | `ArrayList>` | Always `null` for query (errors throw `SkyflowException`). | + +### `FileUploadResponse` + +`com.skyflow.vault.data` — returned by `vault().uploadFile()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getSkyflowId()` | `String` | ID of the record the file was attached to (or of the newly created record). | +| `getErrors()` | `ArrayList>` | Errors, if any. | + +### `DetokenizeResponse` + +`com.skyflow.vault.tokens` — returned by `vault().detokenize()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getDetokenizedFields()` | `ArrayList` | One entry per token. See [`DetokenizeRecordResponse`](#detokenizerecordresponse). | +| `getErrors()` | `ArrayList` | Per-token errors when `continueOnError=true`. | + +#### `DetokenizeRecordResponse` + +Each element returned by `getDetokenizedFields()` and `getErrors()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getToken()` | `String` | The input token value. | +| `getValue()` | `String` | The detokenized plaintext (or masked) value. `null` on error. | +| `getType()` | `String` | The value type (e.g. `"STRING"`). `null` on error. | +| `getError()` | `String` | Error message. `null` on success. | +| `getRequestId()` | `String` | Server request ID for this token. Useful for support escalations. | + +### `TokenizeResponse` + +`com.skyflow.vault.tokens` — returned by `vault().tokenize()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getTokens()` | `List` | One token per input `ColumnValue`, in order. | + +### `DeidentifyTextResponse` + +`com.skyflow.vault.detect` — returned by `detect().deidentifyText()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getProcessedText()` | `String` | The de-identified text with entity values replaced by tokens. | +| `getEntities()` | `List` | Detected entities. See [`EntityInfo`](#entityinfo). | +| `getWordCount()` | `int` | Word count of the input text. | +| `getCharCount()` | `int` | Character count of the input text. | + +### `ReidentifyTextResponse` + +`com.skyflow.vault.detect` — returned by `detect().reidentifyText()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getProcessedText()` | `String` | The re-identified text with tokens replaced by their original values. | + +### `DeidentifyFileResponse` + +`com.skyflow.vault.detect` — returned by `detect().deidentifyFile()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getFile()` | `FileInfo` | Metadata about the processed file. See [`FileInfo`](#fileinfo). | +| `getFileBase64()` | `String` | Base64-encoded processed file content (when `outputProcessedImage=true`). | +| `getType()` | `String` | MIME type of the output file. | +| `getExtension()` | `String` | File extension of the output file. | +| `getWordCount()` | `Integer` | Word count (text/document files). | +| `getCharCount()` | `Integer` | Character count (text/document files). | +| `getSizeInKb()` | `Float` | Output file size in kilobytes. | +| `getDurationInSeconds()` | `Float` | Duration in seconds (audio/video files). | +| `getPageCount()` | `Integer` | Page count (PDF files). | +| `getSlideCount()` | `Integer` | Slide count (presentation files). | +| `getEntities()` | `List` | Detected entities. See [`FileEntityInfo`](#fileentityinfo). | +| `getRunId()` | `String` | Run ID for async polling with `getDetectRun()`. | +| `getStatus()` | `String` | Processing status. See [`DeidentifyFileStatus`](#deidentifyfilestatus). | + +### `InvokeConnectionResponse` + +`com.skyflow.vault.connection` — returned by `connection().invoke()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getData()` | `Object` | The response body from the downstream service. | +| `getMetadata()` | `HashMap` | Response metadata (e.g. HTTP headers forwarded by the connection). | +| `getErrors()` | `ArrayList>` | Errors, if any. | + +--- + +## Helper classes + +### `DetokenizeData` + +`com.skyflow.vault.tokens` — used inside [`DetokenizeRequest`](#detokenizerequest). + +| Constructor | Description | +|-------------|-------------| +| `new DetokenizeData(String token)` | Detokenize with default redaction (`RedactionType.PLAIN_TEXT`). | +| `new DetokenizeData(String token, RedactionType redactionType)` | Detokenize with a specific redaction type. | + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getToken()` | `String` | The token value. | +| `getRedactionType()` | `RedactionType` | The redaction type applied to the result. | + +### `ColumnValue` + +`com.skyflow.vault.tokens` — used inside [`TokenizeRequest`](#tokenizerequest). + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `value(String)` | _(required)_ | The value to tokenize. | +| `columnGroup(String)` | _(required)_ | The column group that defines the tokenization policy. | + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getValue()` | `String` | The value to tokenize. | +| `getColumnGroup()` | `String` | The column group name. | + +### `FileInput` + +`com.skyflow.vault.detect` — used inside [`DeidentifyFileRequest`](#deidentifyfilerequest). Provide exactly one source. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `file(File)` | `null` | A `java.io.File` object. | +| `filePath(String)` | `null` | Path to a file. | + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getFile()` | `File` | The file object. | +| `getFilePath()` | `String` | The file path. | + +### `AudioBleep` + +`com.skyflow.vault.detect` — used inside [`DeidentifyFileRequest`](#deidentifyfilerequest) for audio bleeping. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `gain(Double)` | `null` | Gain level of the bleep tone. | +| `frequency(Double)` | `null` | Frequency (Hz) of the bleep tone. | +| `startPadding(Double)` | `null` | Seconds of silence before the bleep. | +| `stopPadding(Double)` | `null` | Seconds of silence after the bleep. | + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getGain()` | `Double` | Gain level. | +| `getFrequency()` | `Double` | Frequency. | +| `getStartPadding()` | `Double` | Start padding in seconds. | +| `getStopPadding()` | `Double` | Stop padding in seconds. | + +### `TokenFormat` + +`com.skyflow.vault.detect` — used inside [`DeidentifyTextRequest`](#deidentifytextrequest) and [`DeidentifyFileRequest`](#deidentifyfilerequest) to control token types per entity. + +| Builder method | Default | Description | +|----------------|---------|-------------| +| `defaultType(TokenType)` | `TokenType.ENTITY_UNIQUE_COUNTER` | Default token type for entities not explicitly listed. See [`TokenType`](#tokentype). | +| `vaultToken(List)` | `null` | Entities to tokenize as vault tokens. | +| `entityUniqueCounter(List)` | `null` | Entities to tokenize as entity-unique-counter tokens. | +| `entityOnly(List)` | `null` | Entities to tokenize as entity-only tokens. | + +### `Transformations` + +`com.skyflow.vault.detect` — used inside [`DeidentifyTextRequest`](#deidentifytextrequest) and [`DeidentifyFileRequest`](#deidentifyfilerequest). + +| Constructor | Description | +|-------------|-------------| +| `new Transformations(DateTransformation shiftDates)` | Apply date shifting. | + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getShiftDates()` | `DateTransformation` | The date transformation to apply. | + +### `DateTransformation` + +`com.skyflow.vault.detect` — used inside [`Transformations`](#transformations). + +| Constructor | Description | +|-------------|-------------| +| `new DateTransformation(int max, int min, List entities)` | Shift dates by a random amount within `[min, max]` days. | + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getMax()` | `int` | Maximum day-shift value. | +| `getMin()` | `int` | Minimum day-shift value. | +| `getEntities()` | `List` | Entity types to date-shift. | + +### `EntityInfo` + +`com.skyflow.vault.detect` — element of `DeidentifyTextResponse.getEntities()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getToken()` | `String` | The token that replaced the original entity value. | +| `getValue()` | `String` | The original entity value. | +| `getTextIndex()` | `TextIndex` | Character offsets of the entity in the original text. | +| `getProcessedIndex()` | `TextIndex` | Character offsets of the token in the processed text. | +| `getEntity()` | `String` | Entity type label (e.g. `"EMAIL_ADDRESS"`). | +| `getScores()` | `Map` | Confidence scores per entity type. | + +### `TextIndex` + +`com.skyflow.vault.detect` — used in [`EntityInfo`](#entityinfo). + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getStart()` | `int` | Start character offset (inclusive). | +| `getEnd()` | `int` | End character offset (exclusive). | + +### `FileEntityInfo` + +`com.skyflow.vault.detect` — element of `DeidentifyFileResponse.getEntities()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getFile()` | `String` | File name or identifier. | +| `getType()` | `String` | Output file type. | +| `getExtension()` | `String` | Output file extension. | + +### `FileInfo` + +`com.skyflow.vault.detect` — returned by `DeidentifyFileResponse.getFile()`. + +| Getter | Return type | Description | +|--------|-------------|-------------| +| `getName()` | `String` | Original file name. | +| `getSize()` | `long` | File size in bytes. | +| `getType()` | `String` | MIME type. | +| `getLastModified()` | `long` | Last-modified timestamp (milliseconds since epoch). | + +--- + +## Enums + +### `LogLevel` + +`com.skyflow.enums` + +| Value | Description | +|-------|-------------| +| `OFF` | Disable all logging. | +| `ERROR` | Log errors only. _(default)_ | +| `WARN` | Log warnings and errors. | +| `INFO` | Log informational messages, warnings, and errors. | +| `DEBUG` | Log everything (DEBUG, INFO, WARN, ERROR). | + +### `Env` + +`com.skyflow.enums` + +| Value | Description | +|-------|-------------| +| `PROD` | Production environment. _(default)_ | +| `SANDBOX` | Sandbox environment. | +| `STAGE` | Staging environment. | +| `DEV` | Development environment. | + +### `RedactionType` + +`com.skyflow.enums` + +| Value | Description | +|-------|-------------| +| `PLAIN_TEXT` | Return the original, unmasked value. | +| `MASKED` | Return a partially masked value (e.g. `****1234`). | +| `REDACTED` | Return a fully redacted placeholder. | +| `DEFAULT` | Use the redaction type configured on the vault column. | + +### `TokenMode` + +`com.skyflow.enums` — controls bring-your-own-token (BYOT) behavior for `insert` and `update`. + +| Value | Description | +|-------|-------------| +| `DISABLE` | Do not use BYOT tokens. _(default)_ | +| `ENABLE` | Use provided tokens where supplied; generate tokens for missing fields. | +| `ENABLE_STRICT` | All fields must supply a BYOT token; missing tokens cause an error. | + +### `TokenType` + +`com.skyflow.enums` — used in [`TokenFormat`](#tokenformat) for Detect operations. + +| Value | Description | +|-------|-------------| +| `VAULT_TOKEN` | Token stored in the vault and associated with a skyflow_id. | +| `ENTITY_UNIQUE_COUNTER` | Deterministic token unique to the entity value (consistent across occurrences). | +| `ENTITY_ONLY` | Token represents the entity type only, with no value stored in the vault. | + +### `RequestMethod` + +`com.skyflow.enums` — used in [`InvokeConnectionRequest`](#invokeconnectionrequest). + +| Value | Description | +|-------|-------------| +| `GET` | HTTP GET. | +| `POST` | HTTP POST. _(default for connections)_ | +| `PUT` | HTTP PUT. | +| `PATCH` | HTTP PATCH. | +| `DELETE` | HTTP DELETE. | + +### `MaskingMethod` + +`com.skyflow.enums` — used in [`DeidentifyFileRequest`](#deidentifyfilerequest). + +| Value | Description | +|-------|-------------| +| `BLACKBOX` | Cover detected entities with a solid black rectangle. | +| `BLUR` | Blur detected entities. | + +### `DetectOutputTranscriptions` + +`com.skyflow.enums` — used in [`DeidentifyFileRequest`](#deidentifyfilerequest). + +| Value | Description | +|-------|-------------| +| `TRANSCRIPTION` | Standard transcription. | +| `DIARIZED_TRANSCRIPTION` | Transcription with speaker diarization. | +| `MEDICAL_TRANSCRIPTION` | Medical-domain transcription. | +| `MEDICAL_DIARIZED_TRANSCRIPTION` | Medical transcription with speaker diarization. | + +### `DeidentifyFileStatus` + +`com.skyflow.enums` — returned in `DeidentifyFileResponse.getStatus()`. + +| Value | Description | +|-------|-------------| +| `IN_PROGRESS` | File processing is ongoing. Poll with `getDetectRun()`. | +| `SUCCESS` | Processing completed successfully. | +| `FAILED` | Processing failed. | +| `UNKNOWN` | Status could not be determined. | + +### `DetectEntities` + +`com.skyflow.enums` — entity type values for Detect operations. + +| Category | Values | +|----------|--------| +| Personal identity | `NAME`, `NAME_GIVEN`, `NAME_FAMILY`, `NAME_MEDICAL_PROFESSIONAL`, `DOB`, `AGE`, `GENDER`, `MARITAL_STATUS`, `SEXUALITY`, `RELIGION`, `POLITICAL_AFFILIATION`, `PHYSICAL_ATTRIBUTE`, `ORIGIN`, `NATIONALITY` | +| Contact | `EMAIL_ADDRESS`, `PHONE_NUMBER`, `LOCATION`, `LOCATION_ADDRESS`, `LOCATION_ADDRESS_STREET`, `LOCATION_CITY`, `LOCATION_STATE`, `LOCATION_COUNTRY`, `LOCATION_ZIP`, `LOCATION_COORDINATE` | +| Financial | `CREDIT_CARD`, `CREDIT_CARD_EXPIRATION`, `CVV`, `BANK_ACCOUNT`, `ACCOUNT_NUMBER`, `ROUTING_NUMBER`, `MONEY`, `FINANCIAL_METRIC`, `CORPORATE_ACTION` | +| Government ID | `SSN`, `DRIVER_LICENSE`, `PASSPORT_NUMBER`, `HEALTHCARE_NUMBER`, `ORGANIZATION_ID`, `NUMERICAL_PII` | +| Medical | `BLOOD_TYPE`, `CONDITION`, `DRUG`, `DOSE`, `EFFECT`, `INJURY`, `MEDICAL_CODE`, `MEDICAL_PROCESS`, `ORGANIZATION_MEDICAL_FACILITY` | +| Date & time | `DATE`, `DAY`, `MONTH`, `YEAR`, `TIME`, `DURATION`, `DATE_INTERVAL`, `EVENT` | +| Technology | `IP_ADDRESS`, `URL`, `USERNAME`, `PASSWORD`, `FILENAME`, `VEHICLE_ID` | +| Organization | `ORGANIZATION`, `OCCUPATION`, `PROJECT`, `PRODUCT` | +| Other | `LANGUAGE`, `STATISTICS`, `TREND`, `ZODIAC_SIGN`, `ALL` | + +Use `DetectEntities.ALL` to detect all supported entity types. + +--- + +## Service account utilities + +### `BearerToken` builder + +`com.skyflow.serviceaccount.util` — generates bearer tokens from service account credentials. Tokens are valid for 60 minutes. + +| Builder method | Description | +|----------------|-------------| +| `setCredentials(File)` | Path to a service account `credentials.json` file. | +| `setCredentials(String)` | Service account credentials as a JSON string. | +| `setCtx(String)` | Embed a string context value in the token for context-aware authorization. | +| `setCtx(Map)` | Embed a map of context values. Keys must match `[a-zA-Z0-9_]`. | +| `setRoles(ArrayList)` | Scope the token to specific role IDs. | +| `build()` | Build the `BearerToken` instance. | + +| Method | Return type | Description | +|--------|-------------|-------------| +| `getBearerToken()` | `String` | Generate and return a bearer token string. | + +```java +// Check expiry before regenerating +if (Token.isExpired(token)) { + BearerToken bt = BearerToken.builder() + .setCredentials(new File("")) + .build(); + token = bt.getBearerToken(); +} +``` + +### `SignedDataTokens` builder + +`com.skyflow.serviceaccount.util` — signs data tokens with the service account's private key for secure detokenization. + +| Builder method | Description | +|----------------|-------------| +| `setCredentials(File)` | Path to a service account `credentials.json` file. | +| `setCredentials(String)` | Service account credentials as a JSON string. | +| `setCtx(String)` | Embed a string context value. | +| `setCtx(Map)` | Embed a map of context values. | +| `setDataTokens(List)` | The data tokens to sign. | +| `setTimeToLive(int)` | TTL in seconds (default: `60`). | +| `build()` | Build and return signed data token records. | + +Response: a `List` of objects, each with: + +| Field | Description | +|-------|-------------| +| `dataToken` | The original data token. | +| `signedDataToken` | The signed token string (JWT). | + +### `Token` utility + +`com.skyflow.serviceaccount.util` + +| Method | Return type | Description | +|--------|-------------|-------------| +| `Token.isExpired(String token)` | `boolean` | Returns `true` if the token is `null` or has expired. Use before every API call to avoid mid-flight expiry. |