SK-2708 fix readme and sample gaps

samples/README.md

@@ -64,23 +64,28 @@ Sample files are organized by API type:
 
 **Vault API samples** ([`vault-api/`](vault-api/)):
 - [`insert-records.ts`](vault-api/insert-records.ts) - Insert data and get tokens
-- [`insert-continue-on-error.ts`](vault-api/insert-continue-on-error.ts) - Bulk insert with error handling
-- [`insert-byot.ts`](vault-api/insert-byot.ts) - Upsert operations
+- [`insert-continue-on-error.ts`](vault-api/insert-continue-on-error.ts) - Bulk insert with per-record error handling
+- [`insert-byot.ts`](vault-api/insert-byot.ts) - Insert with bring-your-own tokens (BYOT)
 - [`get-records.ts`](vault-api/get-records.ts) - Retrieve records by Skyflow IDs
 - [`get-column-values.ts`](vault-api/get-column-values.ts) - Query by column values
 - [`detokenzie-records.ts`](vault-api/detokenzie-records.ts) - Convert tokens to values
 - [`tokenize-records.ts`](vault-api/tokenize-records.ts) - Get tokens for existing values
 - [`update-record.ts`](vault-api/update-record.ts) - Update existing records
 - [`delete-records.ts`](vault-api/delete-records.ts) - Delete records by ID
 - [`query-records.ts`](vault-api/query-records.ts) - SQL query operations
-- [`file-upload.ts`](vault-api/file-upload.ts) - Upload files to vault
+- [`file-upload.ts`](vault-api/file-upload.ts) - Upload files to vault (file path, base64, or File object)
 - [`invoke-connection.ts`](vault-api/invoke-connection.ts) - Call external integrations
+- [`client-operations.ts`](vault-api/client-operations.ts) - Runtime vault and connection management
+- [`credentials-options.ts`](vault-api/credentials-options.ts) - All credential types and multi-vault setup
+- [`data-residency.ts`](vault-api/data-residency.ts) - Multi-region vault configuration
 
 **Detect API samples** ([`detect-api/`](detect-api/)):
 - [`deidentify-text.ts`](detect-api/deidentify-text.ts) - Anonymize text data
-- [`deidentify-file.ts`](detect-api/deidentify-file.ts) - Anonymize file data
-- [`reidentify-text.ts`](detect-api/reidentify-text.ts) - Restore original values
-- [`get-detect-run.ts`](detect-api/get-detect-run.ts) - Check operation status
+- [`deidentify-file.ts`](detect-api/deidentify-file.ts) - Anonymize a file using a File object
+- [`deidentify-file-with-filepath.ts`](detect-api/deidentify-file-with-filepath.ts) - Anonymize a file using a file path
+- [`deidentify-file-with-filepath-async.ts`](detect-api/deidentify-file-with-filepath-async.ts) - Anonymize a file asynchronously (poll for result)
+- [`reidentify-text.ts`](detect-api/reidentify-text.ts) - Restore original values from de-identified text
+- [`get-detect-run.ts`](detect-api/get-detect-run.ts) - Check the status of an async de-identify operation
 
 **Service Account samples** ([`service-account/`](service-account/)):
 - [`token-generation-example.ts`](service-account/token-generation-example.ts) - Generate bearer tokens

samples/detect-api/deidentify-file-with-filepath-async.ts

@@ -131,7 +131,7 @@ import {
       // Comprehensive Error Handling
       if (error instanceof SkyflowError) {
         console.error('Skyflow Specific Error:', {
-          code: error.error?.http_code,
+          code: error.error?.httpCode,
           message: error.message,
           details: error.error?.details,
         });

samples/detect-api/deidentify-text.ts

@@ -61,15 +61,28 @@ async function performDeidentifyText() {
         // setEntities: Specify which entities to deidentify
         options.setEntities([DetectEntities.CREDIT_CARD, DetectEntities.SSN]);
 
-        // setAllowRegexList: Allowlist regex patterns (entities matching these will not be deidentified)
-        // optionsText.setAllowRegexList(['<YOUR_REGEX_PATTERN>']);
+        // Allowlist: regex patterns whose matches will NOT be de-identified
+        // options.setAllowRegexList(['<YOUR_REGEX_PATTERN>']);
 
-        // setRestrictRegexList: Restrict de-identification to entities matching these regex patterns
-        // optionsText.setRestrictRegexList(['<YOUR_REGEX_PATTERN>']);
+        // Denylist: restrict de-identification to only entities matching these patterns
+        // options.setRestrictRegexList(['<YOUR_REGEX_PATTERN>']);
 
-        // setTokenFormat: Specify the token format for deidentified entities
+        // setTokenFormat: choose how de-identified entities are represented as tokens
         const tokenFormat = new TokenFormat();
+
+        // Apply one token type as the default for all entity types
         tokenFormat.setDefault(TokenType.VAULT_TOKEN);
+
+        // --- Per-entity-type token format overrides (optional) ---
+        // Use vault tokens only for specific entity types
+        // tokenFormat.setVaultToken([DetectEntities.SSN, DetectEntities.CREDIT_CARD]);
+
+        // Use an entity-unique counter token for specific entity types
+        // tokenFormat.setEntityUniqueCounter([DetectEntities.NAME]);
+
+        // Use entity-only (no token) for specific entity types
+        // tokenFormat.setEntityOnly([DetectEntities.DATE_OF_BIRTH]);
+
         options.setTokenFormat(tokenFormat);
 
         // setTransformations: Specify custom transformations for entities

samples/vault-api/credentials-options.ts

@@ -70,9 +70,9 @@ async function performSecureDataDeletion() {
 
         // Step 4: Prepare Delete Request for Primary Vault
         const primaryDeleteIds: Array<string> = [
-            'skyflow_id1',
-            'skyflow_id2',
-            'skyflow_id3',
+            '<SKYFLOW_ID_1>',
+            '<SKYFLOW_ID_2>',
+            '<SKYFLOW_ID_3>',
         ];
 
         const primaryTableName: string = '<primary_table_name>';   // Replace with actual table name
@@ -91,9 +91,9 @@ async function performSecureDataDeletion() {
 
         // Step 5: Prepare Delete Request for Secondary Vault
         const secondaryDeleteIds: Array<string> = [
-            'skyflow_id4',
-            'skyflow_id5',
-            'skyflow_id6',
+            '<SKYFLOW_ID_4>',
+            '<SKYFLOW_ID_5>',
+            '<SKYFLOW_ID_6>',
         ];
 
         const secondaryTableName: string = '<secondary_table_name>'; // Replace with actual table name

samples/vault-api/delete-records.ts

@@ -44,7 +44,7 @@ async function performDeletion() {
         const skyflowClient: Skyflow = new Skyflow(skyflowConfig);
 
         // Step 4: Prepare Delete Data
-        const deleteIds: Array<string> = ['skyflow_id1', 'skyflow_id2', 'skyflow_id3']; // Record IDs to delete
+        const deleteIds: Array<string> = ['<SKYFLOW_ID_1>', '<SKYFLOW_ID_2>', '<SKYFLOW_ID_3>']; // Record IDs to delete
         const tableName: string = 'sensitive_data_table'; // Table name in the vault schema
 
         // Create Delete Request

samples/vault-api/detokenzie-records.ts

@@ -27,7 +27,7 @@ async function performDetokenization() {
     try {
         // Step 1: Configure Credentials
         const credentials: Credentials = {
-            token: 'token', // Bearer token for authentication
+            token: '<BEARER_TOKEN>',
         };
 
         // Step 2: Configure Vault

samples/vault-api/file-upload.ts

@@ -15,63 +15,69 @@ import * as fs from 'fs';
 
 /**
  * Skyflow File Upload Example
- * 
- * This example demonstrates how to:
- * 1. Configure credentials
- * 2. Set up vault configuration
- * 3. Create a file upload request
- * 4. Handle response and errors
- * 
- * Note: File upload requires Node version 20 or above.
+ *
+ * This example demonstrates how to upload a file to a Skyflow vault using three
+ * different file source options — pick exactly one per upload:
+ *   Option A: setFilePath()   — read a file from disk by path (simplest for server-side Node.js)
+ *   Option B: setBase64()     — supply file content as a base64-encoded string
+ *   Option C: setFileObject() — supply an in-memory File object directly
+ *
+ * Note: File upload requires Node.js v20 or above.
  */
 async function performFileUpload() {
     try {
-        // Step 1: Configure Credentials
+        // Step 1: Configure credentials
         const credentials: Credentials = {
-            path: 'path-to-credentials-json', // Path to credentials file
+            path: '<YOUR_CREDENTIALS_FILE_PATH>',
         };
 
-        // Step 2: Configure Vault 
+        // Step 2: Configure vault
         const primaryVaultConfig: VaultConfig = {
-            vaultId: 'your-vault-id',          // Unique vault identifier
-            clusterId: 'your-cluster-id',      // From vault URL
-            env: Env.PROD,                     // Deployment environment
-            credentials: credentials           // Authentication method
+            vaultId: '<VAULT_ID>',
+            clusterId: '<CLUSTER_ID>',
+            env: Env.PROD,
+            credentials: credentials,
         };
 
-        // Step 3: Configure Skyflow Client
+        // Step 3: Initialize Skyflow client
         const skyflowConfig: SkyflowConfig = {
             vaultConfigs: [primaryVaultConfig],
-            logLevel: LogLevel.ERROR,               // Logging verbosity
+            logLevel: LogLevel.ERROR,
         };
-
-        // Initialize Skyflow Client
         const skyflowClient: Skyflow = new Skyflow(skyflowConfig);
 
-        // Step 4: Prepare File Upload Data
-        const tableName: string = 'table-name';      // Table name
-        const skyflowId: string = 'skyflow-id';      // Skyflow ID of the record
-        const columnName: string = 'column-name';    // Column name to store file
-        const filePath: string = 'file-path';        // Path to the file for upload
-
-        // Step 5: Create File Upload Request (SK-2812: 2-arg constructor, skyflowId moved to options)
+        // Step 4: Create a file upload request (table + column only; Skyflow ID goes in options)
         const uploadReq: FileUploadRequest = new FileUploadRequest(
-            tableName,
-            columnName,
+            '<TABLE_NAME>',
+            '<COLUMN_NAME>',
         );
 
-        // Step 6: Configure FileUpload Options
+        // Step 5: Configure upload options — set Skyflow ID, then choose one file source
+
         const uploadOptions: FileUploadOptions = new FileUploadOptions();
-        uploadOptions.setSkyflowId(skyflowId); // SK-2812: new API
-        uploadOptions.setFilePath(filePath);
 
-        // Step 6: Perform File Upload
+        // Required: the Skyflow ID of the record to attach this file to
+        uploadOptions.setSkyflowId('<SKYFLOW_ID>');
+
+        // --- Option A: File path (SDK reads the file from disk) ---
+        uploadOptions.setFilePath('<FILE_PATH>');
+
+        // --- Option B: Base64-encoded content ---
+        // const base64Content = fs.readFileSync('<FILE_PATH>').toString('base64');
+        // uploadOptions.setBase64(base64Content);
+        // uploadOptions.setFileName('document.pdf'); // required when using setBase64
+
+        // --- Option C: In-memory File object ---
+        // const buffer = fs.readFileSync('<FILE_PATH>');
+        // uploadOptions.setFileObject(new File([buffer], 'document.pdf'));
+
+        // Step 6: Upload the file
         const response: FileUploadResponse = await skyflowClient
             .vault(primaryVaultConfig.vaultId)
             .uploadFile(uploadReq, uploadOptions);
 
-        // Handle Successful Response
         console.log('File upload successful:', response);
+        console.log('Skyflow ID:', response.skyflowId);
 
     } catch (error) {
         // Comprehensive Error Handling

samples/vault-api/get-column-values.ts

@@ -1,13 +1,15 @@
-import { 
-    Env, 
-    GetOptions, 
-    LogLevel, 
-    Skyflow, 
-    GetColumnRequest, 
-    Credentials, 
-    SkyflowConfig, 
-    VaultConfig, 
-    SkyflowError, 
+import {
+    Env,
+    GetOptions,
+    LogLevel,
+    OrderByEnum,
+    RedactionType,
+    Skyflow,
+    GetColumnRequest,
+    Credentials,
+    SkyflowConfig,
+    VaultConfig,
+    SkyflowError,
     GetResponse,
     GetResponseData
 } from 'skyflow-node';
@@ -62,7 +64,24 @@ async function performSecureColumnRetrieval() {
 
         // Step 6: Configure Get Options
         const getOptions: GetOptions = new GetOptions();
-        getOptions.setReturnTokens(true); // Optional: Get tokens for retrieved data
+
+        // Return tokens instead of plain-text values (default: false)
+        getOptions.setReturnTokens(true);
+
+        // Control how sensitive data is redacted in the response
+        // getOptions.setRedactionType(RedactionType.PLAIN_TEXT);
+
+        // Limit the response to specific field names
+        // getOptions.setFields(['card_number', 'cardholder_name']);
+
+        // Pagination: skip the first N records
+        // getOptions.setOffset('10');
+
+        // Pagination: return at most N records
+        // getOptions.setLimit('20');
+
+        // Sort order for returned records
+        // getOptions.setOrderBy(OrderByEnum.ASCENDING);
 
         // Step 7: Perform Secure Retrieval
         const response: GetResponse = await skyflowClient

samples/vault-api/get-records.ts

@@ -1,13 +1,15 @@
-import { 
-    Credentials, 
-    Env, 
-    GetOptions, 
-    GetRequest, 
-    LogLevel, 
-    Skyflow, 
-    VaultConfig, 
-    SkyflowConfig, 
-    SkyflowError, 
+import {
+    Credentials,
+    Env,
+    GetOptions,
+    GetRequest,
+    LogLevel,
+    OrderByEnum,
+    RedactionType,
+    Skyflow,
+    VaultConfig,
+    SkyflowConfig,
+    SkyflowError,
     GetResponse,
     GetResponseData
 } from 'skyflow-node';
@@ -59,11 +61,33 @@ async function performSecureDataRetrieval() {
 
         // Step 6: Configure Get Options
         const getOptions: GetOptions = new GetOptions();
+
+        // Return tokens instead of plain-text values (default: false)
         getOptions.setReturnTokens(true);
 
-        // NEW API (SK-2812): setDownloadUrl (camelCase)
-        getOptions.setDownloadUrl(false);
+        // Control how sensitive data is redacted in the response
+        // getOptions.setRedactionType(RedactionType.PLAIN_TEXT);
+
+        // Limit the response to specific field names
+        // getOptions.setFields(['card_number', 'cardholder_name']);
+
+        // Pagination: skip the first N records
+        // getOptions.setOffset('10');
+
+        // Pagination: return at most N records
+        // getOptions.setLimit('20');
+
+        // Sort order for returned records
+        // getOptions.setOrderBy(OrderByEnum.ASCENDING);
+
+        // --- Alternative: query by column value instead of Skyflow IDs ---
+        // (use with a GetRequest that has no IDs; setColumnName + setColumnValues together)
+        // getOptions.setColumnName('card_number');
+        // getOptions.setColumnValues(['4111111111111112']);
 
+        // Return a pre-signed download URL for file fields
+        // getOptions.setDownloadUrl(true);
+
         // DEPRECATED API — still works, logs WARN: setDownloadURL (uppercase URL)
         // getOptions.setDownloadURL(false);
 

samples/vault-api/insert-byot.ts

@@ -26,7 +26,7 @@ async function performSecureDataInsertionWithBYOT() {
     try {
         // Step 1: Configure Credentials
         const credentials: Credentials = {
-            token: 'bearer', // Bearer token authentication
+            token: '<BEARER_TOKEN>',
         };
 
         // Step 2: Configure Vault
@@ -48,7 +48,7 @@ async function performSecureDataInsertionWithBYOT() {
 
         // Step 4: Prepare Insertion Data
         const insertData: Record<string, unknown>[] = [
-            { card_number: 'skyflow_id1', card_cvv: 'skyflow_id2' },
+            { card_number: '<TOKEN_1>', card_cvv: '<TOKEN_2>' },
         ];
 
         const tableName: string = 'your-table-name';

samples/vault-api/insert-records.ts

@@ -60,8 +60,19 @@ async function performSecureDataInsertion() {
 
         // Step 6: Configure Insertion Options
         const insertOptions: InsertOptions = new InsertOptions();
-        insertOptions.setReturnTokens(true);  // Optional: Get tokens for inserted data
-        // insertOptions.setContinueOnError(true);  // Optional: Continue on partial errors
+
+        // Return tokens for inserted fields (default: false)
+        insertOptions.setReturnTokens(true);
+
+        // Continue inserting remaining records even when some fail (batch mode)
+        // insertOptions.setContinueOnError(true);
+
+        // Upsert: update the record if a matching value exists in the specified column
+        // (the column must have the `unique` constraint in the vault schema)
+        // insertOptions.setUpsertColumn('card_number');
+
+        // Homogeneous insert: treat all records as the same schema for a bulk insert
+        // insertOptions.setHomogeneous(true);
 
         // Step 7: Perform Secure Insertion
         const response: InsertResponse = await skyflowClient