@ondewo/nlu-client-typescript 6.14.0 → 7.0.0

package/auth/offlineTokenProvider.js

@@ -50,13 +50,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OfflineTokenProvider = exports.TokenError = void 0;
 exports.createDefaultTokenFetch = createDefaultTokenFetch;
 exports.login = login;
-// D18 headless-SDK auth helper (keycloak-migration-plan §7.8 + D18).
-//
-// One-time ROPC login (grant_type=password, scope=offline_access) against the PUBLIC SDK client
-// `ondewo-nlu-cai-sdk-public` (no client_secret -- Q1), then a bounded background loop that refreshes
-// the short-lived access token from the offline refresh token before it expires. The current access
-// token is exposed for an `Authorization: Bearer <token>` gRPC metadata header. The refresh loop stops
-// after `tokenExpirationInS` (if given) has elapsed since login.
+/**
+ * D18 headless-SDK auth helper (keycloak-migration-plan §7.8 + D18).
+ *
+ * One-time ROPC login (grant_type=password, scope=offline_access) against the PUBLIC SDK client
+ * `ondewo-nlu-cai-sdk-public` (no client_secret -- Q1), then a bounded background loop that refreshes
+ * the short-lived access token from the offline refresh token before it expires. The current access
+ * token is exposed for an `Authorization: Bearer <token>` gRPC metadata header. The refresh loop stops
+ * after `tokenExpirationInS` (if given) has elapsed since login.
+ *
+ * @packageDocumentation
+ */
 /**
  * Seconds of head-room subtracted from a token's `expires_in` so the refresh fires before the access
  * token actually lapses (covers clock skew + the round-trip to Keycloak).
@@ -64,16 +68,22 @@ exports.login = login;
 const REFRESH_SKEW_IN_S = 30;
 /** Lower bound for the scheduled refresh delay so a tiny/zero `expires_in` cannot spin a hot loop. */
 const MIN_REFRESH_DELAY_IN_S = 1;
-/** Error raised on any token-endpoint or token-shape failure. */
+/**
+ * Error raised on any token-endpoint or token-shape failure.
+ *
+ * Name contract: every instance carries `name === "TokenError"` (set in the constructor, because
+ * subclassing `Error` does not propagate the subclass name). Callers may therefore discriminate on
+ * `error.name` as well as on `instanceof TokenError` -- the latter being unreliable across bundles.
+ */
 class TokenError extends Error {
     /**
-     * Construct a token error.
+     * Construct a token error and pin its `name` to `"TokenError"`.
      *
      * @param message - Human-readable description of the token failure.
      */
     constructor(message) {
         super(message);
-        this.name = "TokenError";
+        this.name = 'TokenError';
     }
 }
 exports.TokenError = TokenError;
@@ -86,7 +96,7 @@ exports.TokenError = TokenError;
  * @returns The fully-qualified `.../realms/<realm>/protocol/openid-connect/token` endpoint URL.
  */
 function buildTokenEndpoint(keycloakUrl, realm) {
-    const base = keycloakUrl.replace(/\/+$/, "");
+    const base = keycloakUrl.replace(/\/+$/, '');
     return `${base}/realms/${encodeURIComponent(realm)}/protocol/openid-connect/token`;
 }
 /**
@@ -102,10 +112,10 @@ function buildTokenEndpoint(keycloakUrl, realm) {
 async function postTokenRequest(tokenEndpoint, params, fetchImpl) {
     const body = new URLSearchParams(params).toString();
     const response = await fetchImpl(tokenEndpoint, {
-        method: "POST",
+        method: 'POST',
         headers: {
-            "Content-Type": "application/x-www-form-urlencoded",
-            Accept: "application/json"
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Accept: 'application/json'
         },
         body
     });
@@ -120,8 +130,8 @@ async function postTokenRequest(tokenEndpoint, params, fetchImpl) {
     catch {
         throw new TokenError(`Keycloak token endpoint returned a non-JSON body: ${text}`);
     }
-    if (typeof parsed.access_token !== "string" || parsed.access_token.length === 0) {
-        throw new TokenError("Keycloak token response did not contain an access_token");
+    if (typeof parsed.access_token !== 'string' || parsed.access_token.length === 0) {
+        throw new TokenError('Keycloak token response did not contain an access_token');
     }
     return parsed;
 }
@@ -133,15 +143,16 @@ let insecureNodeDispatcher;
  * so a browser bundle never pulls in `undici` and the flag stays a hard no-op outside Node.
  *
  * @returns The insecure dispatcher under Node, or `undefined` in a browser (TLS is owned by the browser).
+ * @throws {Error} When the dynamic `import("undici")` cannot be resolved under Node.
  */
 async function getInsecureNodeDispatcher() {
     const nodeProcess = globalThis.process;
-    /* c8 ignore next 3 -- browser guard: not exercised under the Node test runner */
+    // Browser guard: outside Node there is no `process`, so the insecure dispatcher is a hard no-op.
     if (nodeProcess === undefined || nodeProcess.versions === undefined || nodeProcess.versions.node === undefined) {
         return undefined;
     }
     if (insecureNodeDispatcher === undefined) {
-        const undiciModuleName = "undici";
+        const undiciModuleName = 'undici';
         const undici = (await Promise.resolve(`${undiciModuleName}`).then(s => __importStar(require(s))));
         insecureNodeDispatcher = new undici.Agent({ connect: { rejectUnauthorized: false } });
     }
@@ -182,8 +193,7 @@ class OfflineTokenProvider {
         // A custom fetchImpl always wins (the verifySsl flag is ignored for injected transports); only the
         // DEFAULT transport honors verifySsl, and only under Node. Absent/undefined verifySsl => secure (true).
         const verifySsl = options.keycloakVerifySsl !== false;
-        this.fetchImpl =
-            options.fetchImpl !== undefined ? options.fetchImpl : createDefaultTokenFetch(verifySsl);
+        this.fetchImpl = options.fetchImpl !== undefined ? options.fetchImpl : createDefaultTokenFetch(verifySsl);
         this.nowInMs = options.nowInMs !== undefined ? options.nowInMs : Date.now;
         this.accessToken = null;
         this.refreshToken = null;
@@ -202,17 +212,17 @@ class OfflineTokenProvider {
      */
     async bootstrap(username, password) {
         const tokenResponse = await postTokenRequest(this.tokenEndpoint, {
-            grant_type: "password",
+            grant_type: 'password',
             client_id: this.clientId,
             username,
             password,
-            scope: "offline_access"
+            scope: 'offline_access'
         }, this.fetchImpl);
         this.accessToken = tokenResponse.access_token;
-        this.refreshToken = typeof tokenResponse.refresh_token === "string" ? tokenResponse.refresh_token : null;
+        this.refreshToken = typeof tokenResponse.refresh_token === 'string' ? tokenResponse.refresh_token : null;
         if (this.refreshToken === null) {
-            throw new TokenError("Keycloak token response did not contain a refresh_token; the SDK client must have " +
-                "directAccessGrants + the offline_access scope (ondewo-nlu-cai-sdk-public)");
+            throw new TokenError('Keycloak token response did not contain a refresh_token; the SDK client must have ' +
+                'directAccessGrants + the offline_access scope (ondewo-nlu-cai-sdk-public)');
         }
         if (this.tokenExpirationInS !== undefined) {
             const expirationInMs = this.tokenExpirationInS * 1000;
@@ -227,7 +237,8 @@ class OfflineTokenProvider {
      * @throws {TokenError} When the refresh token-endpoint call fails or returns an invalid body.
      */
     async refresh() {
-        /* c8 ignore next 3 -- unreachable: stop() always clears the only timer that calls refresh() */
+        // Defensive: stop() clears the only timer that calls refresh(), so this is normally unreachable
+        // from the scheduler -- it still guards a direct/racing invocation.
         if (this.stopped) {
             return;
         }
@@ -238,13 +249,13 @@ class OfflineTokenProvider {
             return;
         }
         const tokenResponse = await postTokenRequest(this.tokenEndpoint, {
-            grant_type: "refresh_token",
+            grant_type: 'refresh_token',
             client_id: this.clientId,
             refresh_token: this.refreshToken
         }, this.fetchImpl);
         this.accessToken = tokenResponse.access_token;
         // Keycloak may rotate the offline refresh token; keep the newest one when present.
-        if (typeof tokenResponse.refresh_token === "string" && tokenResponse.refresh_token.length > 0) {
+        if (typeof tokenResponse.refresh_token === 'string' && tokenResponse.refresh_token.length > 0) {
             this.refreshToken = tokenResponse.refresh_token;
         }
         this.scheduleRefresh(tokenResponse.expires_in);
@@ -260,7 +271,7 @@ class OfflineTokenProvider {
         if (this.stopped) {
             return;
         }
-        const expiresInS = typeof expiresInRaw === "number" && expiresInRaw > 0 ? expiresInRaw : MIN_REFRESH_DELAY_IN_S;
+        const expiresInS = typeof expiresInRaw === 'number' && expiresInRaw > 0 ? expiresInRaw : MIN_REFRESH_DELAY_IN_S;
         let delayInS = Math.max(expiresInS - REFRESH_SKEW_IN_S, MIN_REFRESH_DELAY_IN_S);
         if (this.deadlineInMs !== null) {
             const remainingInMs = this.deadlineInMs - this.nowInMs();
@@ -279,9 +290,9 @@ class OfflineTokenProvider {
                 }
             });
         }, delayInS * 1000);
-        // Do not keep the event loop alive solely for the refresh timer.
-        /* c8 ignore next 3 -- the else branch is unreachable: Node's Timeout always exposes unref() */
-        if (typeof this.timer.unref === "function") {
+        // Do not keep the event loop alive solely for the refresh timer. Node's Timeout exposes unref();
+        // a browser's numeric handle does not, hence the guard.
+        if (typeof this.timer.unref === 'function') {
             this.timer.unref();
         }
     }
@@ -296,7 +307,12 @@ class OfflineTokenProvider {
     /**
      * Read the current access token.
      *
-     * @returns The current access token, or `null` before bootstrap / after the bounded loop has lapsed.
+     * Once {@link bootstrap} has succeeded this never returns `null` again: when the bounded refresh
+     * loop lapses (or {@link stop} is called) the LAST fetched token keeps being returned even though
+     * it is by then expiring/expired. Callers must treat an `UNAUTHENTICATED` gRPC response -- not a
+     * `null` here -- as the signal to re-login.
+     *
+     * @returns The current access token, or `null` before {@link bootstrap} has completed.
      */
     getAccessToken() {
         return this.accessToken;
@@ -305,15 +321,21 @@ class OfflineTokenProvider {
      * Build the value for an `Authorization` gRPC metadata header.
      *
      * @returns The `Bearer <access_token>` header value.
-     * @throws {TokenError} When no access token is available (login not completed or already lapsed).
+     * @throws {TokenError} When no access token has been fetched yet, i.e. {@link bootstrap} /
+     *   {@link login} has not completed. It does NOT throw once the refresh loop has lapsed -- see
+     *   {@link getAccessToken}.
      */
     getAuthorizationHeader() {
         if (this.accessToken === null) {
-            throw new TokenError("No access token available; login() has not completed or has lapsed");
+            throw new TokenError('No access token available; login() has not completed or has lapsed');
         }
         return `Bearer ${this.accessToken}`;
     }
-    /** Stop the auto-refresh loop. Idempotent; safe to call from any state. */
+    /**
+     * Stop the auto-refresh loop. Idempotent; safe to call from any state. It disarms the pending timer
+     * and suppresses further scheduling, but deliberately KEEPS the last access token readable through
+     * {@link getAccessToken} / {@link getAuthorizationHeader}.
+     */
     stop() {
         this.stopped = true;
         if (this.timer !== null) {
@@ -335,18 +357,12 @@ exports.OfflineTokenProvider = OfflineTokenProvider;
  */
 async function login(options) {
     if (options === undefined || options === null) {
-        throw new TokenError("login() requires an options object");
+        throw new TokenError('login() requires an options object');
     }
-    const requiredKeys = [
-        "keycloakUrl",
-        "realm",
-        "clientId",
-        "username",
-        "password"
-    ];
+    const requiredKeys = ['keycloakUrl', 'realm', 'clientId', 'username', 'password'];
     for (const key of requiredKeys) {
         const value = options[key];
-        if (typeof value !== "string" || value.length === 0) {
+        if (typeof value !== 'string' || value.length === 0) {
             throw new TokenError(`login() option "${key}" is required and must be a non-empty string`);
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ondewo/nlu-client-typescript",
-  "version": "6.14.0",
+  "version": "7.0.0",
   "description": "ONDEWO Natural Language Understanding (NLU) Client library for Typescript",
   "author": "ONDEWO GmbH <office@ondewo.com>",
   "homepage": "https://ondewo.com",
@@ -26,14 +26,16 @@
     "undici": "^6.27.0"
   },
   "devDependencies": {
-    "@eslint/eslintrc": "^3.1.0",
-    "@eslint/js": "^9.13.0",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^9.39.4",
     "@types/node": "^22.15.27",
-    "@typescript-eslint/eslint-plugin": "^8.12.2",
+    "@typescript-eslint/eslint-plugin": "^8.63.0",
     "dotenv": "^16.4.5",
-    "eslint": "^9.13.0",
+    "eslint": "^9.39.4",
     "global": "^4.4.0",
-    "husky": "^9.1.6",
-    "prettier": "^3.3.3"
+    "husky": "^9.1.7",
+    "prettier": "^3.9.4",
+    "c8": "^11.0.0",
+    "typescript": "^6.0.3"
   }
 }

package/public-api.d.ts

@@ -1,44 +1,44 @@
-export * from './api/ondewo/nlu/user_pb.d';
-export * from './api/ondewo/nlu/session_grpc_web_pb.d';
+export * from './api/ondewo/qa/qa_pb.d';
+export * from './api/ondewo/qa/qa_grpc_web_pb.d';
+export * from './api/ondewo/nlu/rag_grpc_web_pb.d';
+export * from './api/ondewo/nlu/llm_evaluation_grpc_web_pb.d';
 export * from './api/ondewo/nlu/user_grpc_web_pb.d';
-export * from './api/ondewo/nlu/project_role_pb.d';
-export * from './api/ondewo/nlu/context_pb.d';
-export * from './api/ondewo/nlu/intent_pb.d';
-export * from './api/ondewo/nlu/server_statistics_grpc_web_pb.d';
-export * from './api/ondewo/nlu/webhook_grpc_web_pb.d';
+export * from './api/ondewo/nlu/utility_grpc_web_pb.d';
+export * from './api/ondewo/nlu/operations_pb.d';
 export * from './api/ondewo/nlu/webhook_pb.d';
 export * from './api/ondewo/nlu/context_grpc_web_pb.d';
-export * from './api/ondewo/nlu/llm_evaluation_grpc_web_pb.d';
-export * from './api/ondewo/nlu/entity_type_pb.d';
-export * from './api/ondewo/nlu/project_statistics_grpc_web_pb.d';
-export * from './api/ondewo/nlu/agent_grpc_web_pb.d';
-export * from './api/ondewo/nlu/operations_grpc_web_pb.d';
-export * from './api/ondewo/nlu/session_pb.d';
-export * from './api/ondewo/nlu/rag_pb.d';
-export * from './api/ondewo/nlu/agent_pb.d';
-export * from './api/ondewo/nlu/intent_grpc_web_pb.d';
-export * from './api/ondewo/nlu/aiservices_grpc_web_pb.d';
-export * from './api/ondewo/nlu/operations_pb.d';
-export * from './api/ondewo/nlu/common_pb.d';
 export * from './api/ondewo/nlu/operation_metadata_pb.d';
-export * from './api/ondewo/nlu/ccai_project_pb.d';
-export * from './api/ondewo/nlu/project_role_grpc_web_pb.d';
-export * from './api/ondewo/nlu/entity_type_grpc_web_pb.d';
 export * from './api/ondewo/nlu/ccai_project_grpc_web_pb.d';
-export * from './api/ondewo/nlu/utility_pb.d';
-export * from './api/ondewo/nlu/rag_grpc_web_pb.d';
+export * from './api/ondewo/nlu/ccai_project_pb.d';
 export * from './api/ondewo/nlu/llm_evaluation_pb.d';
-export * from './api/ondewo/nlu/project_statistics_pb.d';
+export * from './api/ondewo/nlu/intent_grpc_web_pb.d';
+export * from './api/ondewo/nlu/agent_grpc_web_pb.d';
+export * from './api/ondewo/nlu/webhook_grpc_web_pb.d';
+export * from './api/ondewo/nlu/utility_pb.d';
+export * from './api/ondewo/nlu/project_statistics_grpc_web_pb.d';
+export * from './api/ondewo/nlu/user_pb.d';
+export * from './api/ondewo/nlu/entity_type_pb.d';
 export * from './api/ondewo/nlu/aiservices_pb.d';
+export * from './api/ondewo/nlu/entity_type_grpc_web_pb.d';
+export * from './api/ondewo/nlu/server_statistics_grpc_web_pb.d';
 export * from './api/ondewo/nlu/server_statistics_pb.d';
-export * from './api/ondewo/nlu/utility_grpc_web_pb.d';
-export * from './api/ondewo/qa/qa_pb.d';
-export * from './api/ondewo/qa/qa_grpc_web_pb.d';
-export * from './api/google/protobuf/timestamp_pb.d';
-export * from './api/google/protobuf/field_mask_pb.d';
+export * from './api/ondewo/nlu/operations_grpc_web_pb.d';
+export * from './api/ondewo/nlu/intent_pb.d';
+export * from './api/ondewo/nlu/project_role_pb.d';
+export * from './api/ondewo/nlu/context_pb.d';
+export * from './api/ondewo/nlu/agent_pb.d';
+export * from './api/ondewo/nlu/session_pb.d';
+export * from './api/ondewo/nlu/project_role_grpc_web_pb.d';
+export * from './api/ondewo/nlu/common_pb.d';
+export * from './api/ondewo/nlu/aiservices_grpc_web_pb.d';
+export * from './api/ondewo/nlu/rag_pb.d';
+export * from './api/ondewo/nlu/session_grpc_web_pb.d';
+export * from './api/ondewo/nlu/project_statistics_pb.d';
+export * from './api/google/api/annotations_pb.d';
+export * from './api/google/rpc/status_pb.d';
 export * from './api/google/protobuf/empty_pb.d';
-export * from './api/google/protobuf/struct_pb.d';
+export * from './api/google/protobuf/field_mask_pb.d';
+export * from './api/google/protobuf/timestamp_pb.d';
 export * from './api/google/protobuf/any_pb.d';
+export * from './api/google/protobuf/struct_pb.d';
 export * from './api/google/type/latlng_pb.d';
-export * from './api/google/api/annotations_pb.d';
-export * from './api/google/rpc/status_pb.d';

package/public-api.js

@@ -1,44 +1,44 @@
-export * from './api/ondewo/nlu/ccai_project_pb';
-export * from './api/ondewo/nlu/agent_pb';
-export * from './api/ondewo/nlu/rag_pb';
-export * from './api/ondewo/nlu/project_statistics_grpc_web_pb';
-export * from './api/ondewo/nlu/llm_evaluation_grpc_web_pb';
+export * from './api/ondewo/qa/qa_pb';
+export * from './api/ondewo/qa/qa_grpc_web_pb';
+export * from './api/ondewo/nlu/project_role_pb';
+export * from './api/ondewo/nlu/operation_metadata_pb';
+export * from './api/ondewo/nlu/agent_grpc_web_pb';
+export * from './api/ondewo/nlu/session_grpc_web_pb';
 export * from './api/ondewo/nlu/aiservices_pb';
+export * from './api/ondewo/nlu/project_statistics_grpc_web_pb';
+export * from './api/ondewo/nlu/rag_pb';
 export * from './api/ondewo/nlu/session_pb';
 export * from './api/ondewo/nlu/server_statistics_grpc_web_pb';
-export * from './api/ondewo/nlu/webhook_grpc_web_pb';
+export * from './api/ondewo/nlu/context_pb';
+export * from './api/ondewo/nlu/ccai_project_grpc_web_pb';
 export * from './api/ondewo/nlu/operations_grpc_web_pb';
+export * from './api/ondewo/nlu/webhook_pb';
 export * from './api/ondewo/nlu/aiservices_grpc_web_pb';
-export * from './api/ondewo/nlu/server_statistics_pb';
-export * from './api/ondewo/nlu/project_role_grpc_web_pb';
+export * from './api/ondewo/nlu/intent_pb';
 export * from './api/ondewo/nlu/utility_grpc_web_pb';
-export * from './api/ondewo/nlu/user_pb';
-export * from './api/ondewo/nlu/operations_pb';
-export * from './api/ondewo/nlu/entity_type_pb';
+export * from './api/ondewo/nlu/agent_pb';
+export * from './api/ondewo/nlu/project_role_grpc_web_pb';
 export * from './api/ondewo/nlu/rag_grpc_web_pb';
-export * from './api/ondewo/nlu/agent_grpc_web_pb';
-export * from './api/ondewo/nlu/project_statistics_pb';
-export * from './api/ondewo/nlu/project_role_pb';
-export * from './api/ondewo/nlu/context_grpc_web_pb';
-export * from './api/ondewo/nlu/utility_pb';
+export * from './api/ondewo/nlu/llm_evaluation_pb';
+export * from './api/ondewo/nlu/entity_type_pb';
+export * from './api/ondewo/nlu/ccai_project_pb';
+export * from './api/ondewo/nlu/user_grpc_web_pb';
 export * from './api/ondewo/nlu/intent_grpc_web_pb';
-export * from './api/ondewo/nlu/ccai_project_grpc_web_pb';
-export * from './api/ondewo/nlu/session_grpc_web_pb';
+export * from './api/ondewo/nlu/utility_pb';
+export * from './api/ondewo/nlu/server_statistics_pb';
+export * from './api/ondewo/nlu/webhook_grpc_web_pb';
+export * from './api/ondewo/nlu/project_statistics_pb';
 export * from './api/ondewo/nlu/entity_type_grpc_web_pb';
-export * from './api/ondewo/nlu/context_pb';
-export * from './api/ondewo/nlu/intent_pb';
-export * from './api/ondewo/nlu/user_grpc_web_pb';
-export * from './api/ondewo/nlu/webhook_pb';
+export * from './api/ondewo/nlu/user_pb';
+export * from './api/ondewo/nlu/context_grpc_web_pb';
 export * from './api/ondewo/nlu/common_pb';
-export * from './api/ondewo/nlu/llm_evaluation_pb';
-export * from './api/ondewo/nlu/operation_metadata_pb';
-export * from './api/ondewo/qa/qa_pb';
-export * from './api/ondewo/qa/qa_grpc_web_pb';
-export * from './api/google/protobuf/timestamp_pb';
+export * from './api/ondewo/nlu/llm_evaluation_grpc_web_pb';
+export * from './api/ondewo/nlu/operations_pb';
+export * from './api/google/api/annotations_pb';
+export * from './api/google/rpc/status_pb';
+export * from './api/google/protobuf/field_mask_pb';
 export * from './api/google/protobuf/any_pb';
+export * from './api/google/protobuf/timestamp_pb';
 export * from './api/google/protobuf/empty_pb';
 export * from './api/google/protobuf/struct_pb';
-export * from './api/google/protobuf/field_mask_pb';
 export * from './api/google/type/latlng_pb';
-export * from './api/google/api/annotations_pb';
-export * from './api/google/rpc/status_pb';