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

@@ -3,3 +3,63 @@
 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.
+
+## [Unreleased] — Public Interface Cleanup (v2)
+
+### Breaking Changes
+
+#### Credential field renames
+The credentials JSON object now uses camelCase keys. The old ALL_CAPS variants are accepted for backward compatibility but will be removed in a future release.
+
+| Old key | New key |
+|---|---|
+| `clientID` | `clientId` |
+| `keyID` | `keyId` |
+| `tokenURI` | `tokenUri` |
+
+**Migration:**
+```diff
+- { clientID: '...', keyID: '...', tokenURI: '...' }
++ { clientId: '...', keyId: '...', tokenUri: '...' }
+```
+
+#### `BearerTokenOptions.roleIDs` → `roleIds`
+```diff
+- generateBearerToken(path, { roleIDs: ['role1'] })
++ generateBearerToken(path, { roleIds: ['role1'] })
+```
+
+#### `SkyflowError.error.request_ID` → `requestId`
+```diff
+- error.error.request_ID
++ error.error.requestId
+```
+
+#### `FileUploadRequest` — `skyflowId` removed from constructor
+`skyflowId` is no longer a positional argument. Set it via `FileUploadOptions.setSkyflowId()` instead.
+```diff
+- new FileUploadRequest(table, skyflowId, columnName)
++ const req = new FileUploadRequest(table, columnName)
++ const opts = new FileUploadOptions()
++ opts.setSkyflowId(skyflowId)
+```
+
+#### `DetokenizeOptions` / `GetOptions` — `downloadURL` → `downloadUrl`
+```diff
+- options.setDownloadURL(true)
++ options.setDownloadUrl(true)
+```
+
+#### `Bleep` — `start_padding` / `stop_padding` → `startPadding` / `stopPadding`
+```diff
+- bleep.setStartPadding(start_padding)
+- bleep.setStopPadding(stop_padding)
++ bleep.setStartPadding(startPadding)
++ bleep.setStopPadding(stopPadding)
+```
+
+### Behavior Changes
+
+- **`insertedFields` always array**: `InsertResponse.insertedFields` is now `Array<InsertResponseType>` (never `null`). An empty array is returned when there are no successful records.
+- **Fail-fast validation**: `insert()` now throws `SkyflowError` (EMPTY_FIELD) before any network call when a record field value is `null`, `undefined`, or `""`. Values `0`, `false`, and `0.0` remain valid.
+- **`errors` always present**: All response objects (`Insert`, `Update`, `Get`, `Delete`, `Query`, `Tokenize`, `DeidentifyText`, `DeidentifyFile`) always include an `errors` field — `null` when there are no errors, never absent.

README.md

@@ -197,11 +197,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 +271,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)
@@ -857,11 +857,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 +873,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,39 @@
+{
+  "$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"
+      }
+    }
+  }
+}