@centrali-io/centrali-sdk 4.4.1 → 4.4.2

package/README.md

@@ -40,20 +40,36 @@ console.log('Found:', results.data.totalHits, 'results');
 
 ## Authentication
 
-The SDK supports two authentication methods:
+The SDK supports three authentication methods. See the [full authentication guide](../docs/sdk/authentication.md) for details.
 
-### Bearer Token (User Authentication)
+### Publishable Key (Frontend Apps)
+
+Safe to use in browser code. Scoped to specific resources.
+
+```typescript
+const centrali = new CentraliSDK({
+  baseUrl: 'https://centrali.io',
+  workspaceId: 'your-workspace',
+  publishableKey: 'pk_live_your_key_here'
+});
+```
+
+### External Token / BYOT (Clerk, Auth0, etc.)
+
+Dynamic token callback for apps with their own auth.
 
 ```typescript
 const centrali = new CentraliSDK({
   baseUrl: 'https://centrali.io',
   workspaceId: 'your-workspace',
-  token: 'your-jwt-token'
+  getToken: async () => await clerk.session.getToken()
 });
 ```
 
 ### Service Account (Server-to-Server)
 
+Never use in browser code. Client secret must stay on the server.
+
 ```typescript
 const centrali = new CentraliSDK({
   baseUrl: 'https://centrali.io',
@@ -61,8 +77,6 @@ const centrali = new CentraliSDK({
   clientId: process.env.CENTRALI_CLIENT_ID,
   clientSecret: process.env.CENTRALI_CLIENT_SECRET
 });
-
-// The SDK automatically fetches and manages tokens
 ```
 
 ## Features
@@ -79,6 +93,8 @@ const centrali = new CentraliSDK({
 - ✅ **Data Validation** - AI-powered typo detection, format validation, duplicate detection
 - ✅ **Anomaly Insights** - AI-powered anomaly detection and data quality insights
 - ✅ **Orchestrations** - Multi-step workflows with compute functions, decision logic, and delays
+- ✅ **Publishable keys** - Scoped, browser-safe keys for frontend apps
+- ✅ **External auth (BYOT)** - Dynamic token callback for Clerk, Auth0, etc.
 - ✅ **Service accounts** - Automatic token refresh for server-to-server auth
 
 ## Core Operations

package/dist/index.js

@@ -2525,10 +2525,36 @@ class CentraliSDK {
         this.tokenRefreshPromise = null;
         this.options = options;
         this.token = options.token || null;
+        // Validate mutually exclusive auth options
+        const authPaths = [
+            options.publishableKey ? 'publishableKey' : null,
+            options.getToken ? 'getToken' : null,
+            (options.clientId || options.clientSecret) ? 'clientId/clientSecret' : null,
+        ].filter(Boolean);
+        if (options.publishableKey && authPaths.length > 1) {
+            throw new Error(`Cannot use publishableKey with ${authPaths.filter(p => p !== 'publishableKey').join(', ')}. Use one auth method.`);
+        }
+        if (options.getToken && (options.clientId || options.clientSecret)) {
+            throw new Error('Cannot use getToken with clientId/clientSecret. Use one auth method.');
+        }
         const apiUrl = getApiUrl(options.baseUrl);
         this.axios = axios_1.default.create(Object.assign({ baseURL: apiUrl, paramsSerializer: (params) => qs_1.default.stringify(params, { arrayFormat: "repeat" }), proxy: false }, options.axiosConfig));
         // Attach async interceptor to fetch token on first request if needed
         this.axios.interceptors.request.use((config) => __awaiter(this, void 0, void 0, function* () {
+            // Auth path 1: Publishable key — send as x-api-key header, no token logic
+            if (this.options.publishableKey) {
+                config.headers['x-api-key'] = this.options.publishableKey;
+                return config;
+            }
+            // Auth path 2: Dynamic token callback (getToken) — call on each request
+            if (this.options.getToken) {
+                this.token = yield this.options.getToken();
+                if (this.token) {
+                    config.headers.Authorization = `Bearer ${this.token}`;
+                }
+                return config;
+            }
+            // Auth path 3: Client credentials — fetch token on first request
             if (!this.token && this.options.clientId && this.options.clientSecret) {
                 this.token = yield fetchClientToken(this.options.clientId, this.options.clientSecret, this.options.baseUrl);
             }
@@ -2541,10 +2567,26 @@ class CentraliSDK {
         this.axios.interceptors.response.use((response) => response, (error) => __awaiter(this, void 0, void 0, function* () {
             var _a, _b;
             const originalRequest = error.config;
-            // Only attempt refresh for 401/403 errors when using client credentials
+            // Publishable keys: no retry — scope errors are permanent
+            if (this.options.publishableKey) {
+                return Promise.reject(error);
+            }
             const isAuthError = ((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 401 || ((_b = error.response) === null || _b === void 0 ? void 0 : _b.status) === 403;
-            const hasClientCredentials = this.options.clientId && this.options.clientSecret;
             const hasNotRetried = !originalRequest._hasRetried;
+            // getToken path: retry once with a fresh token on 401
+            if (isAuthError && this.options.getToken && hasNotRetried) {
+                originalRequest._hasRetried = true;
+                try {
+                    this.token = yield this.options.getToken();
+                    originalRequest.headers.Authorization = `Bearer ${this.token}`;
+                    return this.axios(originalRequest);
+                }
+                catch (refreshError) {
+                    return Promise.reject(error);
+                }
+            }
+            // Client credentials path: refresh token and retry on 401/403
+            const hasClientCredentials = this.options.clientId && this.options.clientSecret;
             if (isAuthError && hasClientCredentials && hasNotRetried) {
                 // Mark request as retried to prevent infinite loops
                 originalRequest._hasRetried = true;

package/index.ts

@@ -542,11 +542,22 @@ export interface CentraliSDKOptions {
     /** Base URL of Centrali (e.g. https://centrali.io). The SDK automatically uses api.centrali.io for API calls. */
     baseUrl: string;
     workspaceId: string;
+
+    // Auth path 1: Publishable key (frontend apps — safe to expose in browser code)
+    /** Publishable key for frontend access. Sent as x-api-key header. No token refresh needed. */
+    publishableKey?: string;
+
+    // Auth path 2: Bearer token (existing) + dynamic token callback (new)
     /** Optional initial bearer token for authentication */
     token?: string;
+    /** Optional callback to dynamically fetch a fresh token before each request (e.g., for Clerk, Auth0) */
+    getToken?: () => Promise<string>;
+
+    // Auth path 3: Service account (server-side only — never use in browser)
     /** Optional OAuth2 client credentials */
     clientId?: string;
     clientSecret?: string;
+
     /** Optional custom axios config */
     axiosConfig?: AxiosRequestConfig;
 }
@@ -4773,6 +4784,21 @@ export class CentraliSDK {
     constructor(options: CentraliSDKOptions) {
         this.options = options;
         this.token = options.token || null;
+
+        // Validate mutually exclusive auth options
+        const authPaths = [
+            options.publishableKey ? 'publishableKey' : null,
+            options.getToken ? 'getToken' : null,
+            (options.clientId || options.clientSecret) ? 'clientId/clientSecret' : null,
+        ].filter(Boolean);
+
+        if (options.publishableKey && authPaths.length > 1) {
+            throw new Error(`Cannot use publishableKey with ${authPaths.filter(p => p !== 'publishableKey').join(', ')}. Use one auth method.`);
+        }
+        if (options.getToken && (options.clientId || options.clientSecret)) {
+            throw new Error('Cannot use getToken with clientId/clientSecret. Use one auth method.');
+        }
+
         const apiUrl = getApiUrl(options.baseUrl);
         this.axios = axios.create({
             baseURL: apiUrl,
@@ -4785,6 +4811,22 @@ export class CentraliSDK {
         // Attach async interceptor to fetch token on first request if needed
         this.axios.interceptors.request.use(
             async (config) => {
+                // Auth path 1: Publishable key — send as x-api-key header, no token logic
+                if (this.options.publishableKey) {
+                    config.headers['x-api-key'] = this.options.publishableKey;
+                    return config;
+                }
+
+                // Auth path 2: Dynamic token callback (getToken) — call on each request
+                if (this.options.getToken) {
+                    this.token = await this.options.getToken();
+                    if (this.token) {
+                        config.headers.Authorization = `Bearer ${this.token}`;
+                    }
+                    return config;
+                }
+
+                // Auth path 3: Client credentials — fetch token on first request
                 if (!this.token && this.options.clientId && this.options.clientSecret) {
                     this.token = await fetchClientToken(
                         this.options.clientId,
@@ -4806,11 +4848,29 @@ export class CentraliSDK {
             async (error) => {
                 const originalRequest = error.config;
 
-                // Only attempt refresh for 401/403 errors when using client credentials
+                // Publishable keys: no retry — scope errors are permanent
+                if (this.options.publishableKey) {
+                    return Promise.reject(error);
+                }
+
                 const isAuthError = error.response?.status === 401 || error.response?.status === 403;
-                const hasClientCredentials = this.options.clientId && this.options.clientSecret;
                 const hasNotRetried = !originalRequest._hasRetried;
 
+                // getToken path: retry once with a fresh token on 401
+                if (isAuthError && this.options.getToken && hasNotRetried) {
+                    originalRequest._hasRetried = true;
+                    try {
+                        this.token = await this.options.getToken();
+                        originalRequest.headers.Authorization = `Bearer ${this.token}`;
+                        return this.axios(originalRequest);
+                    } catch (refreshError) {
+                        return Promise.reject(error);
+                    }
+                }
+
+                // Client credentials path: refresh token and retry on 401/403
+                const hasClientCredentials = this.options.clientId && this.options.clientSecret;
+
                 if (isAuthError && hasClientCredentials && hasNotRetried) {
                     // Mark request as retried to prevent infinite loops
                     originalRequest._hasRetried = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-sdk",
-  "version": "4.4.1",
+  "version": "4.4.2",
   "description": "Centrali Node SDK",
   "main": "dist/index.js",
   "type": "commonjs",