SK-2812: Public interface cleanup

.github/workflows/common-release.yml

@@ -12,11 +12,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
         with:
           token: ${{ secrets.PAT_ACTIONS }}
           fetch-depth: 0
-      - uses: actions/setup-node@v1
+      - uses: actions/setup-node@v4
         with:
           node-version: '20.x'
           # registry-url: "https://registry.npmjs.org"
@@ -32,10 +32,10 @@ jobs:
         uses: WyriHaximus/github-action-get-previous-tag@v1
         with:
           fallback: 1.0.0
-      
+
       - name: Resolve Branch Name
         id: resolve-branch
-        if: ${{ inputs.tag == 'beta' || inputs.tag == 'public' }} 
+        if: ${{ inputs.tag == 'beta' || inputs.tag == 'public' }}
         run: |
           TAG_COMMIT=$(git rev-list -n 1 ${{ github.ref_name }})
 
@@ -79,12 +79,19 @@ jobs:
           if [[ "${{ inputs.tag }}" == "beta" ]]; then
             npm publish --tag beta
           elif [[ "${{ inputs.tag }}" == "public" ]]; then
-            npm publish
+            MAJOR_VERSION=$(node -p "require('./package.json').version.split('.')[0]")
+            if [[ "$MAJOR_VERSION" == "1" ]]; then
+              npm publish --tag v1
+            else
+              npm publish
+            fi
           elif [[ "${{ inputs.tag }}" == "internal" ]]; then
-            curl -u ${{ secrets.JFROG_USERNAME }}:${{ secrets.JFROG_PASSWORD }} https://prekarilabs.jfrog.io/prekarilabs/api/npm/auth/ > ~/.npmrc
+            JFROG_AUTH=$(echo -n "$JFROG_USERNAME:$JFROG_PASSWORD" | base64 -w 0)
             npm config set registry https://prekarilabs.jfrog.io/prekarilabs/api/npm/npm/
-            npm config fix
+            npm config set //prekarilabs.jfrog.io/prekarilabs/api/npm/npm/:_auth "$JFROG_AUTH"
             npm publish
           fi
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          JFROG_USERNAME: ${{ secrets.JFROG_USERNAME }}
+          JFROG_PASSWORD: ${{ secrets.JFROG_PASSWORD }}

.github/workflows/contract-tests.yml

@@ -0,0 +1,45 @@
+name: Contract Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+      - release/*
+
+jobs:
+  contract-tests:
+    name: Contract Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Verify API surface snapshot
+        run: npm run contract-snapshot-verify
+
+      - name: Show API surface diff
+        if: failure()
+        run: |
+          echo "### API surface changes detected ###"
+          echo "Lines prefixed with '-' were REMOVED from the public API."
+          echo "Lines prefixed with '+' were ADDED to the public API."
+          echo ""
+          diff -u api-report/skyflow-node.api.md temp/skyflow-node.api.md || true
+
+      - name: Upload API surface diff on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: api-surface-diff
+          path: temp/skyflow-node.api.md
+          retention-days: 7

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
-All notable changes to this project will be documented as part of the release notes. 
+All notable changes to this project will be documented as part of the release notes.
 
-See  [Github](https://github.com/skyflowapi/skyflow-node/releases) or [npm](https://www.npmjs.com/package/skyflow-node?activeTab=versions) for more details on each released version.
+See [Github](https://github.com/skyflowapi/skyflow-node/releases) or [npm](https://www.npmjs.com/package/skyflow-node?activeTab=versions) for more details on each released version.
+
+---

README.md

@@ -1,5 +1,7 @@
 # Skyflow Node.js SDK
 
+> **Node.js V2.1.x IS NOW AVAILABLE:** A new, improved version of the Skyflow SDK is ready with flexible authentication, multi-vault support, and richer error diagnostics. V1 is in maintenance mode (security patches only) and will reach End of Life on October 31, 2026. We recommend upgrading to v2 — see the **[Migration Guide](docs/migrate_to_v2.md)** for step-by-step instructions.
+
 Securely handle sensitive data at rest, in-transit, and in-use with the Skyflow SDK for Node.js, Deno, Bun, and Cloudflare Workers.
 
 [![CI](https://img.shields.io/static/v1?label=CI&message=passing&color=green?style=plastic&logo=github)](https://github.com/skyflowapi/skyflow-node/actions)
@@ -197,11 +199,11 @@ console.log("Insert response:", insertResponse);
 
 ## Upgrade from v1 to v2
 
-Upgrade from `skyflow-node` v1 using the dedicated guide in [docs/migrate_to_v2.md](docs/migrate_to_v2.md).
+Upgrade from `skyflow-node` v1 using the dedicated guide in [docs/migrate_to_v2.md](docs/migrate_to_v2.md). For a full list of breaking changes, see [CHANGELOG.md](CHANGELOG.md).
 
 ## Vault
 
-The [Vault](https://docs.skyflow.com/docs/vaults) performs operations on the vault such as inserting records, detokenizing tokens, retrieving tokens for list of `skyflow_id`'s and to invoke the Connection.
+The [Vault](https://docs.skyflow.com/docs/vaults) performs operations on the vault such as inserting records, detokenizing tokens, retrieving tokens for list of `skyflowId`s and to invoke the Connection.
 
 ### Insert and tokenize data: `.insert(request)`
 
@@ -271,7 +273,7 @@ const detokenizeRequest = new DetokenizeRequest([
 
 const detokenizeOptions = new DetokenizeOptions();
 detokenizeOptions.setContinueOnError(true);
-detokenizeOptions.setDownloadURL(false);
+detokenizeOptions.setDownloadUrl(false);
 
 const response: DetokenizeResponse = await skyflowClient
   .vault(primaryVaultConfig.vaultId)
@@ -465,7 +467,7 @@ Refer to [Query your data](https://docs.skyflow.com/query-data/) and [Execute Qu
 
 ### Upload File
 
-Upload files to a Skyflow vault using the `uploadFile` method. Create a file upload request with the `FileUploadRequest` class, which accepts parameters such as the table name, column name, and Skyflow ID. Configure upload options with the `FileUploadOptions` class, which accepts the file object as shown below:
+Upload files to a Skyflow vault using the `uploadFile` method. Create a file upload request with the `FileUploadRequest` class, which accepts the table name and column name. Set the Skyflow ID via `FileUploadOptions.setSkyflowId()`. Configure upload options with the `FileUploadOptions` class, which accepts the file object as shown below:
 
 ```typescript
 // Please use Node version 20 & above to run file upload
@@ -479,19 +481,19 @@ import * as fs from "fs";
 
 // 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 skyflowId: string = "skyflow-id"; // Skyflow ID of the record
 const filePath: string = "file-path"; // Path to the file for upload
 
 // Create File Upload Request
 const uploadReq: FileUploadRequest = new FileUploadRequest(
   tableName,
-  skyflowId,
   columnName,
 );
 
 // Configure FileUpload Options
 const uploadOptions: FileUploadOptions = new FileUploadOptions();
+uploadOptions.setSkyflowId(skyflowId); // Set the Skyflow ID via options
 const buffer = fs.readFileSync(filePath);
 // Set any one of FilePath, Base64 or FileObject in FileUploadOptions
 uploadOptions.setFileObject(new File([buffer], filePath)); // Set a File object
@@ -857,11 +859,11 @@ Alternatively, you can also send the entire credentials as string by using `gene
 
 #### Generate bearer tokens scoped to certain roles
 
-Generate bearer tokens with access limited to a specific role by specifying the appropriate roleID when using a service account with multiple roles. Use this to limit access for services with multiple responsibilities, such as segregating access for billing and analytics. Generated bearer tokens are valid for 60 minutes and can only execute operations permitted by the permissions associated with the designated role.
+Generate bearer tokens with access limited to a specific role by specifying the appropriate roleId when using a service account with multiple roles. Use this to limit access for services with multiple responsibilities, such as segregating access for billing and analytics. Generated bearer tokens are valid for 60 minutes and can only execute operations permitted by the permissions associated with the designated role.
 
 ```ts
 const options = {
-  roleIDs: ['roleID1', 'roleID2'],
+  roleIds: ['roleId1', 'roleId2'],
 };
 ```
 
@@ -873,18 +875,84 @@ const options = {
 
 Embed context values into a bearer token during generation so you can reference those values in your policies. This enables more flexible access controls, such as tracking end-user identity when making API calls using service accounts, and facilitates using signed data tokens during detokenization.
 
-Generate bearer tokens containing context information using a service account with the context_id identifier. Context information is represented as a JWT claim in a Skyflow-generated bearer token. Tokens generated from such service accounts include a context_identifier claim, are valid for 60 minutes, and can be used to make API calls to the Data and Management APIs, depending on the service account's permissions.
+Generate bearer tokens containing context information using a service account with the `context_id` identifier. Context information is represented as a JWT claim in a Skyflow-generated bearer token. Tokens generated from such service accounts include a `context_identifier` claim, are valid for 60 minutes, and can be used to make API calls to the Data and Management APIs, depending on the service account's permissions.
+
+The `ctx` parameter accepts either a **string** or a **JSON object**:
+
+**String context** — use when your policy references a single context value:
+
+```typescript
+const options = {
+  ctx: 'user_12345',
+};
+const response = await generateBearerToken(filepath, options);
+```
+
+**JSON object context** — use when your policy needs multiple context values for conditional data access. Each key in the `ctx` object maps to a Skyflow CEL policy variable under `request.context.*`:
+
+```typescript
+const options = {
+  ctx: {
+    role: 'admin',
+    department: 'finance',
+    user_id: 'user_12345',
+  },
+};
+const response = await generateBearerToken(filepath, options);
+```
+
+With the object above, your Skyflow policies can reference `request.context.role`, `request.context.department`, and `request.context.user_id` to make conditional access decisions.
+
+You can also set the `context` field on credentials for automatic token generation:
+
+```typescript
+// String context on credentials
+const credentials: PathCredentials = {
+  path: 'path/to/credentials.json',
+  context: 'user_12345',
+};
+
+// JSON object context on credentials
+const credentials: PathCredentials = {
+  path: 'path/to/credentials.json',
+  context: {
+    role: 'admin',
+    department: 'finance',
+  },
+};
+```
 
 > [!TIP]
-> See the full example in the samples directory: [token-generation-with-context-example.ts](samples/service-account/token-generation-with-context-example.ts)  
-> See [docs.skyflow.com](https://docs.skyflow.com) for more details on authentication, access control, and governance for Skyflow.
+> See the full example in the samples directory: [token-generation-with-context-example.ts](samples/service-account/token-generation-with-context-example.ts)
+> See Skyflow's [context-aware authorization](https://docs.skyflow.com) and [conditional data access](https://docs.skyflow.com) docs for policy variable syntax like `request.context.*`.
 
 #### Generate signed data tokens: `generateSignedDataTokens(filepath, options)`
 
 Digitally sign data tokens with a service account's private key to add an extra layer of protection. Skyflow generates data tokens when sensitive data is inserted into the vault. Detokenize signed tokens only by providing the signed data token along with a bearer token generated from the service account's credentials. The service account must have the necessary permissions and context to successfully detokenize the signed data tokens.
 
+The `ctx` parameter on signed data tokens also accepts either a **string** or a **JSON object**, using the same format as bearer tokens:
+
+```typescript
+// String context
+const options = {
+  ctx: 'user_12345',
+  dataTokens: ['dataToken1', 'dataToken2'],
+  timeToLive: 90,
+};
+
+// JSON object context
+const options = {
+  ctx: {
+    role: 'analyst',
+    department: 'research',
+  },
+  dataTokens: ['dataToken1', 'dataToken2'],
+  timeToLive: 90,
+};
+```
+
 > [!TIP]
-> See the full example in the samples directory: [signed-token-generation-example.ts](samples/service-account/signed-token-generation-example.ts)  
+> See the full example in the samples directory: [signed-token-generation-example.ts](samples/service-account/signed-token-generation-example.ts)
 > See [docs.skyflow.com](https://docs.skyflow.com) for more details on authentication, access control, and governance for Skyflow.
 
 ## Logging

api-extractor.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "projectFolder": ".",
+  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
+  "bundledPackages": [],
+  "compiler": {
+    "tsconfigFilePath": "<projectFolder>/tsconfig.json"
+  },
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "<projectFolder>/api-report/",
+    "reportTempFolder": "<projectFolder>/temp/",
+    "reportFileName": "<unscopedPackageName>.api.md"
+  },
+  "docModel": {
+    "enabled": false
+  },
+  "dtsRollup": {
+    "enabled": false
+  },
+  "tsdocMetadata": {
+    "enabled": false
+  },
+  "messages": {
+    "compilerMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    },
+    "extractorMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      },
+      "ae-missing-release-tag": {
+        "logLevel": "none"
+      },
+      "ae-setter-with-docs": {
+        "logLevel": "none"
+      }
+    },
+    "tsdocMessageReporting": {
+      "default": {
+        "logLevel": "none"
+      }
+    }
+  }
+}