Node.js SDK: Migrate from V1 to V2

This guide outlines the steps required to migrate the Skyflow Node.js SDK from version 1 (V1) to version 2 (V2).

Authentication

V1 required a bearer token function. V2 lets you choose from five credential types and adds 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: JSON.stringify(process.env.SKYFLOW_CREDENTIALS),
14 };
15 
16 // Option 5: Bearer token
17 const credentials: Credentials = { token: "<YOUR_BEARER_TOKEN>" };

Initialize the client

V2 introduces TypeScript support and multi-vault configuration. 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:

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 if no individual vault credentials are set
15     logLevel: LogLevel.INFO,
16 };
17 
18 const skyflowClient: Skyflow = new Skyflow(skyflowConfig);

Key changes:

vaultURL replaced with clusterId
env is now required (Env.PROD, Env.SANDBOX)
Log level is set per client instance
Full TypeScript support with type definitions

Insert records

V2 uses a typed InsertRequest class instead of a plain object. Responses use typed classes.

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 const insertData: Record<string, unknown>[] = [
2     { card_number: "4111111111111112" },
3 ];
4 
5 const insertReq: InsertRequest = new InsertRequest(
6     "<SENSITIVE_DATA_TABLE>",
7     insertData,
8 );
9 
10 const response: InsertResponse = await skyflowClient
11     .vault("<VAULT_ID>")
12     .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 );

Request options

V2 uses an InsertOptions class with setter methods instead of a plain options object.

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);

Error handling

V2 errors include more detail to help with debugging.

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.

This guide outlines the steps required to migrate the Skyflow Node.js SDK from version 1 (V1) to version 2 (V2).

Authentication

V1 required a bearer token function. V2 lets you choose from five credential types and adds 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: JSON.stringify(process.env.SKYFLOW_CREDENTIALS),
14 };
15 
16 // Option 5: Bearer token
17 const credentials: Credentials = { token: "<YOUR_BEARER_TOKEN>" };

Initialize the client

V2 introduces TypeScript support and multi-vault configuration. 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:

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 if no individual vault credentials are set
15     logLevel: LogLevel.INFO,
16 };
17 
18 const skyflowClient: Skyflow = new Skyflow(skyflowConfig);

Key changes:

vaultURL replaced with clusterId
env is now required (Env.PROD, Env.SANDBOX)
Log level is set per client instance
Full TypeScript support with type definitions

Insert records

V2 uses a typed InsertRequest class instead of a plain object. Responses use typed classes.

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 const insertData: Record<string, unknown>[] = [
2     { card_number: "4111111111111112" },
3 ];
4 
5 const insertReq: InsertRequest = new InsertRequest(
6     "<SENSITIVE_DATA_TABLE>",
7     insertData,
8 );
9 
10 const response: InsertResponse = await skyflowClient
11     .vault("<VAULT_ID>")
12     .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 );

Request options

V2 uses an InsertOptions class with setter methods instead of a plain options object.

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);

Error handling

V2 errors include more detail to help with debugging.

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.

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

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: JSON.stringify(process.env.SKYFLOW_CREDENTIALS),
14	};
15
16	// Option 5: Bearer token
17	const credentials: Credentials = { token: "<YOUR_BEARER_TOKEN>" };

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

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 if no individual vault credentials are set
15	logLevel: LogLevel.INFO,
16	};
17
18	const skyflowClient: Skyflow = new Skyflow(skyflowConfig);

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	});

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

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	}

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

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

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	}