@ondewo/nlu-client-typescript 6.13.0 → 7.0.0

package/api/ondewo/nlu/user_pb.js

@@ -56,8 +56,6 @@ goog.exportSymbol('proto.ondewo.nlu.ListUserPreferencesRequest', null, global);
 goog.exportSymbol('proto.ondewo.nlu.ListUserPreferencesResponse', null, global);
 goog.exportSymbol('proto.ondewo.nlu.ListUsersRequest', null, global);
 goog.exportSymbol('proto.ondewo.nlu.ListUsersResponse', null, global);
-goog.exportSymbol('proto.ondewo.nlu.LoginRequest', null, global);
-goog.exportSymbol('proto.ondewo.nlu.LoginResponse', null, global);
 goog.exportSymbol('proto.ondewo.nlu.ServerRole', null, global);
 goog.exportSymbol('proto.ondewo.nlu.SetUserPreferencesRequest', null, global);
 goog.exportSymbol('proto.ondewo.nlu.SetUserPreferencesResponse', null, global);
@@ -443,48 +441,6 @@ if (goog.DEBUG && !COMPILED) {
    */
   proto.ondewo.nlu.ListServerPermissionsResponse.displayName = 'proto.ondewo.nlu.ListServerPermissionsResponse';
 }
-/**
- * Generated by JsPbCodeGenerator.
- * @param {Array=} opt_data Optional initial data array, typically from a
- * server response, or constructed directly in Javascript. The array is used
- * in place and becomes part of the constructed object. It is not cloned.
- * If no data is provided, the constructed object will be empty, but still
- * valid.
- * @extends {jspb.Message}
- * @constructor
- */
-proto.ondewo.nlu.LoginRequest = function(opt_data) {
-  jspb.Message.initialize(this, opt_data, 0, -1, null, null);
-};
-goog.inherits(proto.ondewo.nlu.LoginRequest, jspb.Message);
-if (goog.DEBUG && !COMPILED) {
-  /**
-   * @public
-   * @override
-   */
-  proto.ondewo.nlu.LoginRequest.displayName = 'proto.ondewo.nlu.LoginRequest';
-}
-/**
- * Generated by JsPbCodeGenerator.
- * @param {Array=} opt_data Optional initial data array, typically from a
- * server response, or constructed directly in Javascript. The array is used
- * in place and becomes part of the constructed object. It is not cloned.
- * If no data is provided, the constructed object will be empty, but still
- * valid.
- * @extends {jspb.Message}
- * @constructor
- */
-proto.ondewo.nlu.LoginResponse = function(opt_data) {
-  jspb.Message.initialize(this, opt_data, 0, -1, null, null);
-};
-goog.inherits(proto.ondewo.nlu.LoginResponse, jspb.Message);
-if (goog.DEBUG && !COMPILED) {
-  /**
-   * @public
-   * @override
-   */
-  proto.ondewo.nlu.LoginResponse.displayName = 'proto.ondewo.nlu.LoginResponse';
-}
 /**
  * Generated by JsPbCodeGenerator.
  * @param {Array=} opt_data Optional initial data array, typically from a
@@ -4545,398 +4501,6 @@ proto.ondewo.nlu.ListServerPermissionsResponse.prototype.setNextPageToken = func
 
 
 
-
-
-if (jspb.Message.GENERATE_TO_OBJECT) {
-/**
- * Creates an object representation of this proto.
- * Field names that are reserved in JavaScript and will be renamed to pb_name.
- * Optional fields that are not set will be set to undefined.
- * To access a reserved field use, foo.pb_<name>, eg, foo.pb_default.
- * For the list of reserved names please see:
- *     net/proto2/compiler/js/internal/generator.cc#kKeyword.
- * @param {boolean=} opt_includeInstance Deprecated. whether to include the
- *     JSPB instance for transitional soy proto support:
- *     http://goto/soy-param-migration
- * @return {!Object}
- */
-proto.ondewo.nlu.LoginRequest.prototype.toObject = function(opt_includeInstance) {
-  return proto.ondewo.nlu.LoginRequest.toObject(opt_includeInstance, this);
-};
-
-
-/**
- * Static version of the {@see toObject} method.
- * @param {boolean|undefined} includeInstance Deprecated. Whether to include
- *     the JSPB instance for transitional soy proto support:
- *     http://goto/soy-param-migration
- * @param {!proto.ondewo.nlu.LoginRequest} msg The msg instance to transform.
- * @return {!Object}
- * @suppress {unusedLocalVariables} f is only used for nested messages
- */
-proto.ondewo.nlu.LoginRequest.toObject = function(includeInstance, msg) {
-  var f, obj = {
-userEmail: jspb.Message.getFieldWithDefault(msg, 1, ""),
-password: jspb.Message.getFieldWithDefault(msg, 2, ""),
-fieldMask: (f = msg.getFieldMask()) && google_protobuf_field_mask_pb.FieldMask.toObject(includeInstance, f)
-  };
-
-  if (includeInstance) {
-    obj.$jspbMessageInstance = msg;
-  }
-  return obj;
-};
-}
-
-
-/**
- * Deserializes binary data (in protobuf wire format).
- * @param {jspb.ByteSource} bytes The bytes to deserialize.
- * @return {!proto.ondewo.nlu.LoginRequest}
- */
-proto.ondewo.nlu.LoginRequest.deserializeBinary = function(bytes) {
-  var reader = new jspb.BinaryReader(bytes);
-  var msg = new proto.ondewo.nlu.LoginRequest;
-  return proto.ondewo.nlu.LoginRequest.deserializeBinaryFromReader(msg, reader);
-};
-
-
-/**
- * Deserializes binary data (in protobuf wire format) from the
- * given reader into the given message object.
- * @param {!proto.ondewo.nlu.LoginRequest} msg The message object to deserialize into.
- * @param {!jspb.BinaryReader} reader The BinaryReader to use.
- * @return {!proto.ondewo.nlu.LoginRequest}
- */
-proto.ondewo.nlu.LoginRequest.deserializeBinaryFromReader = function(msg, reader) {
-  while (reader.nextField()) {
-    if (reader.isEndGroup()) {
-      break;
-    }
-    var field = reader.getFieldNumber();
-    switch (field) {
-    case 1:
-      var value = /** @type {string} */ (reader.readString());
-      msg.setUserEmail(value);
-      break;
-    case 2:
-      var value = /** @type {string} */ (reader.readString());
-      msg.setPassword(value);
-      break;
-    case 3:
-      var value = new google_protobuf_field_mask_pb.FieldMask;
-      reader.readMessage(value,google_protobuf_field_mask_pb.FieldMask.deserializeBinaryFromReader);
-      msg.setFieldMask(value);
-      break;
-    default:
-      reader.skipField();
-      break;
-    }
-  }
-  return msg;
-};
-
-
-/**
- * Serializes the message to binary data (in protobuf wire format).
- * @return {!Uint8Array}
- */
-proto.ondewo.nlu.LoginRequest.prototype.serializeBinary = function() {
-  var writer = new jspb.BinaryWriter();
-  proto.ondewo.nlu.LoginRequest.serializeBinaryToWriter(this, writer);
-  return writer.getResultBuffer();
-};
-
-
-/**
- * Serializes the given message to binary data (in protobuf wire
- * format), writing to the given BinaryWriter.
- * @param {!proto.ondewo.nlu.LoginRequest} message
- * @param {!jspb.BinaryWriter} writer
- * @suppress {unusedLocalVariables} f is only used for nested messages
- */
-proto.ondewo.nlu.LoginRequest.serializeBinaryToWriter = function(message, writer) {
-  var f = undefined;
-  f = message.getUserEmail();
-  if (f.length > 0) {
-    writer.writeString(
-      1,
-      f
-    );
-  }
-  f = message.getPassword();
-  if (f.length > 0) {
-    writer.writeString(
-      2,
-      f
-    );
-  }
-  f = message.getFieldMask();
-  if (f != null) {
-    writer.writeMessage(
-      3,
-      f,
-      google_protobuf_field_mask_pb.FieldMask.serializeBinaryToWriter
-    );
-  }
-};
-
-
-/**
- * optional string user_email = 1;
- * @return {string}
- */
-proto.ondewo.nlu.LoginRequest.prototype.getUserEmail = function() {
-  return /** @type {string} */ (jspb.Message.getFieldWithDefault(this, 1, ""));
-};
-
-
-/**
- * @param {string} value
- * @return {!proto.ondewo.nlu.LoginRequest} returns this
- */
-proto.ondewo.nlu.LoginRequest.prototype.setUserEmail = function(value) {
-  return jspb.Message.setProto3StringField(this, 1, value);
-};
-
-
-/**
- * optional string password = 2;
- * @return {string}
- */
-proto.ondewo.nlu.LoginRequest.prototype.getPassword = function() {
-  return /** @type {string} */ (jspb.Message.getFieldWithDefault(this, 2, ""));
-};
-
-
-/**
- * @param {string} value
- * @return {!proto.ondewo.nlu.LoginRequest} returns this
- */
-proto.ondewo.nlu.LoginRequest.prototype.setPassword = function(value) {
-  return jspb.Message.setProto3StringField(this, 2, value);
-};
-
-
-/**
- * optional google.protobuf.FieldMask field_mask = 3;
- * @return {?proto.google.protobuf.FieldMask}
- */
-proto.ondewo.nlu.LoginRequest.prototype.getFieldMask = function() {
-  return /** @type{?proto.google.protobuf.FieldMask} */ (
-    jspb.Message.getWrapperField(this, google_protobuf_field_mask_pb.FieldMask, 3));
-};
-
-
-/**
- * @param {?proto.google.protobuf.FieldMask|undefined} value
- * @return {!proto.ondewo.nlu.LoginRequest} returns this
-*/
-proto.ondewo.nlu.LoginRequest.prototype.setFieldMask = function(value) {
-  return jspb.Message.setWrapperField(this, 3, value);
-};
-
-
-/**
- * Clears the message field making it undefined.
- * @return {!proto.ondewo.nlu.LoginRequest} returns this
- */
-proto.ondewo.nlu.LoginRequest.prototype.clearFieldMask = function() {
-  return this.setFieldMask(undefined);
-};
-
-
-/**
- * Returns whether this field is set.
- * @return {boolean}
- */
-proto.ondewo.nlu.LoginRequest.prototype.hasFieldMask = function() {
-  return jspb.Message.getField(this, 3) != null;
-};
-
-
-
-
-
-if (jspb.Message.GENERATE_TO_OBJECT) {
-/**
- * Creates an object representation of this proto.
- * Field names that are reserved in JavaScript and will be renamed to pb_name.
- * Optional fields that are not set will be set to undefined.
- * To access a reserved field use, foo.pb_<name>, eg, foo.pb_default.
- * For the list of reserved names please see:
- *     net/proto2/compiler/js/internal/generator.cc#kKeyword.
- * @param {boolean=} opt_includeInstance Deprecated. whether to include the
- *     JSPB instance for transitional soy proto support:
- *     http://goto/soy-param-migration
- * @return {!Object}
- */
-proto.ondewo.nlu.LoginResponse.prototype.toObject = function(opt_includeInstance) {
-  return proto.ondewo.nlu.LoginResponse.toObject(opt_includeInstance, this);
-};
-
-
-/**
- * Static version of the {@see toObject} method.
- * @param {boolean|undefined} includeInstance Deprecated. Whether to include
- *     the JSPB instance for transitional soy proto support:
- *     http://goto/soy-param-migration
- * @param {!proto.ondewo.nlu.LoginResponse} msg The msg instance to transform.
- * @return {!Object}
- * @suppress {unusedLocalVariables} f is only used for nested messages
- */
-proto.ondewo.nlu.LoginResponse.toObject = function(includeInstance, msg) {
-  var f, obj = {
-user: (f = msg.getUser()) && proto.ondewo.nlu.User.toObject(includeInstance, f),
-authToken: jspb.Message.getFieldWithDefault(msg, 2, "")
-  };
-
-  if (includeInstance) {
-    obj.$jspbMessageInstance = msg;
-  }
-  return obj;
-};
-}
-
-
-/**
- * Deserializes binary data (in protobuf wire format).
- * @param {jspb.ByteSource} bytes The bytes to deserialize.
- * @return {!proto.ondewo.nlu.LoginResponse}
- */
-proto.ondewo.nlu.LoginResponse.deserializeBinary = function(bytes) {
-  var reader = new jspb.BinaryReader(bytes);
-  var msg = new proto.ondewo.nlu.LoginResponse;
-  return proto.ondewo.nlu.LoginResponse.deserializeBinaryFromReader(msg, reader);
-};
-
-
-/**
- * Deserializes binary data (in protobuf wire format) from the
- * given reader into the given message object.
- * @param {!proto.ondewo.nlu.LoginResponse} msg The message object to deserialize into.
- * @param {!jspb.BinaryReader} reader The BinaryReader to use.
- * @return {!proto.ondewo.nlu.LoginResponse}
- */
-proto.ondewo.nlu.LoginResponse.deserializeBinaryFromReader = function(msg, reader) {
-  while (reader.nextField()) {
-    if (reader.isEndGroup()) {
-      break;
-    }
-    var field = reader.getFieldNumber();
-    switch (field) {
-    case 1:
-      var value = new proto.ondewo.nlu.User;
-      reader.readMessage(value,proto.ondewo.nlu.User.deserializeBinaryFromReader);
-      msg.setUser(value);
-      break;
-    case 2:
-      var value = /** @type {string} */ (reader.readString());
-      msg.setAuthToken(value);
-      break;
-    default:
-      reader.skipField();
-      break;
-    }
-  }
-  return msg;
-};
-
-
-/**
- * Serializes the message to binary data (in protobuf wire format).
- * @return {!Uint8Array}
- */
-proto.ondewo.nlu.LoginResponse.prototype.serializeBinary = function() {
-  var writer = new jspb.BinaryWriter();
-  proto.ondewo.nlu.LoginResponse.serializeBinaryToWriter(this, writer);
-  return writer.getResultBuffer();
-};
-
-
-/**
- * Serializes the given message to binary data (in protobuf wire
- * format), writing to the given BinaryWriter.
- * @param {!proto.ondewo.nlu.LoginResponse} message
- * @param {!jspb.BinaryWriter} writer
- * @suppress {unusedLocalVariables} f is only used for nested messages
- */
-proto.ondewo.nlu.LoginResponse.serializeBinaryToWriter = function(message, writer) {
-  var f = undefined;
-  f = message.getUser();
-  if (f != null) {
-    writer.writeMessage(
-      1,
-      f,
-      proto.ondewo.nlu.User.serializeBinaryToWriter
-    );
-  }
-  f = message.getAuthToken();
-  if (f.length > 0) {
-    writer.writeString(
-      2,
-      f
-    );
-  }
-};
-
-
-/**
- * optional User user = 1;
- * @return {?proto.ondewo.nlu.User}
- */
-proto.ondewo.nlu.LoginResponse.prototype.getUser = function() {
-  return /** @type{?proto.ondewo.nlu.User} */ (
-    jspb.Message.getWrapperField(this, proto.ondewo.nlu.User, 1));
-};
-
-
-/**
- * @param {?proto.ondewo.nlu.User|undefined} value
- * @return {!proto.ondewo.nlu.LoginResponse} returns this
-*/
-proto.ondewo.nlu.LoginResponse.prototype.setUser = function(value) {
-  return jspb.Message.setWrapperField(this, 1, value);
-};
-
-
-/**
- * Clears the message field making it undefined.
- * @return {!proto.ondewo.nlu.LoginResponse} returns this
- */
-proto.ondewo.nlu.LoginResponse.prototype.clearUser = function() {
-  return this.setUser(undefined);
-};
-
-
-/**
- * Returns whether this field is set.
- * @return {boolean}
- */
-proto.ondewo.nlu.LoginResponse.prototype.hasUser = function() {
-  return jspb.Message.getField(this, 1) != null;
-};
-
-
-/**
- * optional string auth_token = 2;
- * @return {string}
- */
-proto.ondewo.nlu.LoginResponse.prototype.getAuthToken = function() {
-  return /** @type {string} */ (jspb.Message.getFieldWithDefault(this, 2, ""));
-};
-
-
-/**
- * @param {string} value
- * @return {!proto.ondewo.nlu.LoginResponse} returns this
- */
-proto.ondewo.nlu.LoginResponse.prototype.setAuthToken = function(value) {
-  return jspb.Message.setProto3StringField(this, 2, value);
-};
-
-
-
 /**
  * List of repeated fields within this message type.
  * @private {!Array<number>}

package/auth/offlineTokenProvider.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Minimal structural type of the fetch Response fields this helper reads. Keeps the module
+ * self-contained (no DOM lib dependency) while still typing the injectable `fetchImpl`.
+ */
+export interface TokenFetchResponse {
+    /** Whether the HTTP status is in the 2xx success range. */
+    ok: boolean;
+    /** The numeric HTTP status code. */
+    status: number;
+    /**
+     * Read the full response body as text.
+     *
+     * @returns A promise resolving to the raw body string.
+     */
+    text(): Promise<string>;
+}
+/** Init object passed to the injectable fetch. */
+export interface TokenFetchInit {
+    /** HTTP method (always `"POST"` for the token endpoint). */
+    method: string;
+    /** Request headers (content-type and accept). */
+    headers: Record<string, string>;
+    /** The form-encoded request body. */
+    body: string;
+    /**
+     * Optional undici dispatcher (Node only). The default transport attaches an insecure
+     * `Agent({ connect: { rejectUnauthorized: false } })` here when `verifySsl` is `false`; the global
+     * WHATWG fetch honours it. Never set on an injected `fetchImpl` and ignored in a browser bundle.
+     */
+    dispatcher?: unknown;
+}
+/**
+ * Injectable fetch signature (a subset of the global `fetch`) used by the token endpoint call.
+ *
+ * @param url - The token endpoint URL to POST to.
+ * @param init - The request init (method, headers, body).
+ * @returns A promise resolving to the (structurally minimal) response.
+ */
+export type TokenFetch = (url: string, init: TokenFetchInit) => Promise<TokenFetchResponse>;
+/** Options for the D18 headless-SDK offline-token login. */
+export interface OfflineTokenLoginOptions {
+    /** Base Keycloak URL, e.g. "https://auth.example.com/auth" (trailing slash tolerated). */
+    keycloakUrl: string;
+    /** Realm name, e.g. "ondewo-ccai-platform". */
+    realm: string;
+    /** Public SDK client id, e.g. "ondewo-nlu-cai-sdk-public". NO client_secret (Q1). */
+    clientId: string;
+    /** 2FA-exempt technical-user email. */
+    username: string;
+    /** Technical-user password. */
+    password: string;
+    /** Optional cap (seconds) on how long the auto-refresh loop runs after login. */
+    tokenExpirationInS?: number;
+    /** Optional fetch override (tests inject a mock); defaults to the global fetch. */
+    fetchImpl?: TokenFetch;
+    /**
+     * Verify the Keycloak TLS certificate on the token-endpoint call. Default `true` (secure). Set
+     * `false` ONLY for a self-signed local Envoy (e.g. `https://localhost:12001/auth`). Node-only: it is
+     * ignored in a browser bundle (the browser owns TLS) and ignored when a custom `fetchImpl` is
+     * injected. When `false` under Node the default transport attaches an insecure undici dispatcher.
+     */
+    keycloakVerifySsl?: boolean;
+    /** Optional clock override returning epoch ms (tests); defaults to Date.now. */
+    nowInMs?: () => number;
+}
+/**
+ * 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.
+ */
+export declare class TokenError extends Error {
+    /**
+     * Construct a token error and pin its `name` to `"TokenError"`.
+     *
+     * @param message - Human-readable description of the token failure.
+     */
+    constructor(message: string);
+}
+/**
+ * Build the DEFAULT token transport (used only when no `fetchImpl` is injected). It delegates to the
+ * global WHATWG fetch, and -- when `verifySsl` is `false` under Node -- attaches an insecure undici
+ * dispatcher to the request init so the token POST skips certificate verification. With `verifySsl`
+ * `true` (the default) it is a plain pass-through to `globalThis.fetch`, i.e. unchanged behavior.
+ *
+ * @param verifySsl - Whether to verify the Keycloak TLS certificate; `false` opts into the insecure path.
+ * @returns A {@link TokenFetch} that resolves the global fetch at call time (honoring test overrides).
+ */
+export declare function createDefaultTokenFetch(verifySsl: boolean): TokenFetch;
+/**
+ * A live access-token holder backed by a bounded auto-refresh loop. Obtain one from {@link login};
+ * read {@link getAuthorizationHeader} for the gRPC `Authorization` metadata and call {@link stop} when done.
+ */
+export declare class OfflineTokenProvider {
+    /** The realm token endpoint derived from `keycloakUrl` + `realm`. */
+    private readonly tokenEndpoint;
+    /** The public SDK client id sent on every grant. */
+    private readonly clientId;
+    /** Optional cap (seconds) on how long the refresh loop runs after login; `undefined` = unbounded. */
+    private readonly tokenExpirationInS;
+    /** The fetch transport (real global fetch or an injected mock). */
+    private readonly fetchImpl;
+    /** Epoch-ms clock (injectable for deterministic tests; defaults to `Date.now`). */
+    private readonly nowInMs;
+    /**
+     * The current access token, or `null` until {@link bootstrap} has completed. It is NEVER reset to
+     * `null` afterwards: neither {@link stop} nor the bounded deadline clears it.
+     */
+    private accessToken;
+    /** The current offline refresh token, or `null` before bootstrap. */
+    private refreshToken;
+    /** The pending refresh timer handle, or `null` when no refresh is armed. */
+    private timer;
+    /** Whether {@link stop} has been called; suppresses further refresh scheduling. */
+    private stopped;
+    /** Epoch-ms instant past which the loop stops renewing, or `null` when unbounded. */
+    private deadlineInMs;
+    /** Optional callback invoked with the error of a failed background refresh. */
+    private onRefreshErrorHandler;
+    /**
+     * Construct an (un-bootstrapped) provider from login options. Call {@link bootstrap} (or use the
+     * module-level {@link login}) before reading a token.
+     *
+     * @param options - The D18 headless-SDK offline-token login options.
+     */
+    constructor(options: OfflineTokenLoginOptions);
+    /**
+     * Perform the one-time ROPC login and arm the first refresh. Awaited by {@link login}.
+     *
+     * @param username - The 2FA-exempt technical-user email.
+     * @param password - The technical-user password.
+     * @returns A promise that resolves once the initial token is held and the first refresh is armed.
+     * @throws {TokenError} When the token endpoint fails or the response carries no refresh token.
+     */
+    bootstrap(username: string, password: string): Promise<void>;
+    /**
+     * Exchange the offline refresh token for a fresh access token and re-arm the next refresh.
+     *
+     * @returns A promise that resolves once the token is refreshed (or the loop has stopped).
+     * @throws {TokenError} When the refresh token-endpoint call fails or returns an invalid body.
+     */
+    private refresh;
+    /**
+     * Arm a single timer for the next refresh, clamped to the bounded deadline. Stops silently once
+     * `tokenExpirationInS` has elapsed (no further renewal -> access lapses -> re-login required).
+     *
+     * @param expiresInRaw - The `expires_in` (seconds) reported by Keycloak; absent/non-positive
+     *   values fall back to {@link MIN_REFRESH_DELAY_IN_S}.
+     */
+    private scheduleRefresh;
+    /**
+     * Register a callback invoked with the error of a failed background refresh (optional diagnostics).
+     *
+     * @param handler - The callback to receive the refresh error; replaces any previously registered one.
+     */
+    onRefreshError(handler: (error: unknown) => void): void;
+    /**
+     * Read the current access token.
+     *
+     * 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(): string | null;
+    /**
+     * Build the value for an `Authorization` gRPC metadata header.
+     *
+     * @returns The `Bearer <access_token>` header value.
+     * @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(): string;
+    /**
+     * 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(): void;
+}
+/**
+ * One-time ROPC + offline_access login against the PUBLIC SDK client, returning a live token provider
+ * whose access token is auto-refreshed in the background until `tokenExpirationInS` elapses.
+ *
+ * @param options - The headless-SDK login options (`keycloakUrl`, `realm`, `clientId`, `username`,
+ *   `password` are required; `tokenExpirationInS`, `fetchImpl`, `nowInMs` are optional).
+ * @returns A bootstrapped {@link OfflineTokenProvider} holding a live access token.
+ * @throws {TokenError} When required options are missing/empty, the token endpoint fails, or the
+ *   response lacks an access or refresh token.
+ */
+export declare function login(options: OfflineTokenLoginOptions): Promise<OfflineTokenProvider>;