Node.js SDK: Migrate from V1 to V2

Skyflow Node.js SDK v2 introduces a new authentication model, multi-vault support, TypeScript types, typed request and response classes, and richer error diagnostics. This guide walks through the key changes with before-and-after code examples, focuses on Insert end-to-end, then shows how the same pattern applies to other operations. A final section covers the v2.1+ changes — most notably the camelCase migration on error fields — which are backward compatible.

Authentication

V1 required a bearer token function. V2 lets you choose from five credential types and adds full TypeScript support.

V1:

1
const auth = function () {
2
    return new Promise((resolve, reject) => {
3
        resolve(process.env.VAULT_BEARER_TOKEN);
4
    });
5
};

V2:

1
import { Credentials } from 'skyflow-node';
2
3
// Option 1: API key (recommended)
4
const credentials: Credentials = { apiKey: '<YOUR_SKYFLOW_API_KEY>' };
5
6
// Option 2: Environment variable — set SKYFLOW_CREDENTIALS in your environment
7
8
// Option 3: Credentials file
9
const credentials: Credentials = { path: '<YOUR_CREDENTIALS_FILE_PATH>' };
10
11
// Option 4: Stringified JSON
12
const credentials: Credentials = {
13
    credentialsString: process.env.SKYFLOW_CREDENTIALS!,
14
};
15
16
// Option 5: Bearer token
17
const credentials: Credentials = { token: '<YOUR_BEARER_TOKEN>' };

Initialize the client

V2 replaces the static Skyflow.init() factory with a new Skyflow(config) constructor and adds multi-vault support. Log levels are now per-instance instead of global.

V1:

1
const vault = Skyflow.init({
2
    vaultID: 'string',
3
    vaultURL: 'string',
4
    getBearerToken: auth,
5
});

V2 (single vault):

1
import { Credentials, VaultConfig, SkyflowConfig, Env, LogLevel, Skyflow } from 'skyflow-node';
2
3
const credentials: Credentials = { apiKey: '<YOUR_API_KEY>' };
4
5
const primaryVaultConfig: VaultConfig = {
6
    vaultId: '<YOUR_VAULT_ID>',
7
    clusterId: '<YOUR_CLUSTER_ID>', // ID from your vault URL, e.g., https://{clusterId}.vault.skyflowapis.com
8
    env: Env.PROD,
9
    credentials: credentials,
10
};
11
12
const skyflowConfig: SkyflowConfig = {
13
    vaultConfigs: [primaryVaultConfig],
14
    skyflowCredentials: credentials, // Used as a fallback if no per-vault credentials are set
15
    logLevel: LogLevel.INFO,
16
};
17
18
const skyflowClient: Skyflow = new Skyflow(skyflowConfig);

V2 (multiple vaults):

1
const skyflowConfig: SkyflowConfig = {
2
    vaultConfigs: [
3
        {
4
            vaultId: '<PRIMARY_VAULT_ID>',
5
            clusterId: '<PRIMARY_CLUSTER_ID>',
6
            env: Env.PROD,
7
            credentials: primaryCredentials,
8
        },
9
        {
10
            vaultId: '<SECONDARY_VAULT_ID>',
11
            clusterId: '<SECONDARY_CLUSTER_ID>',
12
            env: Env.PROD,
13
            credentials: secondaryCredentials,
14
        },
15
    ],
16
    logLevel: LogLevel.INFO,
17
};
18
19
const skyflowClient: Skyflow = new Skyflow(skyflowConfig);

Key changes:

• vaultURL is replaced by clusterId (derived from your vault URL).
• env is now required. Supported values: Env.PROD, Env.SANDBOX.
• Log level is set per client instance.
• Full TypeScript support with type definitions.
• A single client can manage multiple vault configurations.

Insert records

V2 replaces the plain-object request payload with a typed InsertRequest class. Responses come back as typed InsertResponse objects.

V1:

1
const result = skyflow.insert({
2
    records: [
3
        {
4
            fields: {
5
                card_number: '411111111111111',
6
                expiry_date: '11/22',
7
                fullname: 'firstNameTest',
8
            },
9
            table: 'cards',
10
        },
11
    ],
12
});

V2:

1
import { InsertRequest, InsertResponse } from 'skyflow-node';
2
3
const insertData: Record<string, unknown>[] = [
4
    { card_number: '4111111111111112' },
5
];
6
7
const insertReq: InsertRequest = new InsertRequest(
8
    '<SENSITIVE_DATA_TABLE>',
9
    insertData,
10
);
11
12
const response: InsertResponse = await skyflowClient
13
    .vault('<VAULT_ID>')
14
    .insert(insertReq);

V1 response:

1
{
2
  "records": [
3
    {
4
      "table": "cards",
5
      "fields": {
6
        "card_number": "f37186-e7e2-466f-91e5-48e2bcbc1",
7
        "expiry_date": "1989cb56-63a-4482-adf-1f74cd1a5"
8
      }
9
    }
10
  ]
11
}

V2 response:

1
InsertResponse(
2
    insertedFields: [
3
        {
4
            skyflowId: "ID1",
5
            "<FIELD_NAME1>": "<TOKEN1>",
6
            "<FIELD_NAME2>": "<TOKEN2>"
7
        }
8
    ],
9
    errors: null
10
)

Other operations at a glance

Every vault operation in v2 follows the same pattern: build a typed request, then pass it to a method on the vault client. The snippets below show v2 request construction.

Get:

1
import { GetRequest } from 'skyflow-node';
2
3
const getReq = new GetRequest(
4
    '<TABLE_NAME>',
5
    ['<SKYFLOW_ID_1>', '<SKYFLOW_ID_2>'],
6
);
7
const response = await skyflowClient.vault('<VAULT_ID>').get(getReq);

Update:

1
import { UpdateRequest } from 'skyflow-node';
2
3
const updateReq = new UpdateRequest(
4
    '<TABLE_NAME>',
5
    {
6
        skyflowId: '<SKYFLOW_ID>',
7
        card_number: '<NEW_VALUE>',
8
    },
9
);
10
const response = await skyflowClient.vault('<VAULT_ID>').update(updateReq);

Delete:

1
import { DeleteRequest } from 'skyflow-node';
2
3
const deleteReq = new DeleteRequest(
4
    '<TABLE_NAME>',
5
    ['<SKYFLOW_ID_1>', '<SKYFLOW_ID_2>'],
6
);
7
const response = await skyflowClient.vault('<VAULT_ID>').delete(deleteReq);

Detokenize:

1
import { DetokenizeRequest } from 'skyflow-node';
2
3
const detokenizeReq = new DetokenizeRequest(['<TOKEN_1>', '<TOKEN_2>']);
4
const response = await skyflowClient.vault('<VAULT_ID>').detokenize(detokenizeReq);

Query:

1
import { QueryRequest } from 'skyflow-node';
2
3
const queryReq = new QueryRequest(
4
    'SELECT * FROM <TABLE_NAME> WHERE skyflow_id = "<SKYFLOW_ID>"',
5
);
6
const response = await skyflowClient.vault('<VAULT_ID>').query(queryReq);

Request options

V2 replaces the plain options object with a typed InsertOptions class. Configure it through setters before passing it to the vault call.

V1:

1
const options = {
2
    tokens: true,
3
};

V2:

1
import { InsertOptions } from 'skyflow-node';
2
3
const insertOptions: InsertOptions = new InsertOptions();
4
insertOptions.setReturnTokens(true);
5
insertOptions.setContinueOnError(true);

The same setter-based pattern applies to UpsertOptions, UpdateOptions, DeleteOptions, and GetOptions.

Error handling

V2 errors carry more context to help with debugging. The example below shows the v2.0 field names; see the v2.1+ section for the camelCase canonical names introduced in v2.1.0.

V1:

1
{
2
    code: string | number,
3
    description: string
4
}

V2:

1
{
2
    http_status?: string | number | null,
3
    grpc_code?: string | number | null,
4
    http_code?: string | number | null,
5
    message: string,
6
    request_ID?: string | null,
7
    details?: Array<string> | null,
8
}

Use the request ID field when contacting Skyflow Support — it uniquely identifies the request for faster diagnosis.

v2.1+ updates

v2.1.0 normalizes the public interface to camelCase and introduces several backward-compatible renames. All legacy names continue to work and emit a deprecation warning on use; they will be removed in a future major release.

Error field renames:

SkyflowError and ISkyflowError field names are now canonical camelCase.

SkyflowRecordError.request_ID has been renamed the same way:

Method renames:

If both the legacy and preferred names are provided, the preferred name takes precedence.

FileUploadRequest constructor normalization:

The canonical constructor is now new FileUploadRequest(table, columnName). The legacy 3-argument form new FileUploadRequest(table, skyflowId, columnName) is deprecated; configure skyflowId through FileUploadOptions.setSkyflowId() instead.

1
import { FileUploadRequest, FileUploadOptions } from 'skyflow-node';
2
3
// Preferred (v2.1+)
4
const fileUploadReq = new FileUploadRequest('<TABLE_NAME>', '<COLUMN_NAME>');
5
const fileUploadOpts = new FileUploadOptions();
6
fileUploadOpts.setSkyflowId('<SKYFLOW_ID>');

Credential field aliases:

Credential JSON files now accept camelCase keys alongside the legacy forms. Existing credential files continue to work unchanged.

Response type tightening:

• InsertResponse.insertedFields is guaranteed non-null (returns [] instead of null).
• DeleteResponse.deletedIds is guaranteed defined (returns [] instead of undefined).
• DeidentifyFileResponse and DeidentifyTextResponse now include an errors: Array<SkyflowRecordError> | null field.

Existing === null and === undefined checks against these fields can be replaced with empty-array checks.

Custom token URI:

BearerTokenOptions, SignedDataTokensOptions, and Credentials now accept a tokenUri field to override the default token endpoint URL when generating bearer tokens.

invokeConnection content types:

invokeConnection now correctly handles application/json, application/x-www-form-urlencoded, text/plain, multipart/form-data, text/xml, application/xml, and text/html. Previously, mismatched request/response content types could cause incorrect serialization behavior.

For the full list of changes, see the Node SDK releases on GitHub.

Get help

If you hit issues during migration, contact Skyflow Support and include the requestId from any failed call.