feat: Add getIasToken() and getIasDestination() convenience functions

[davidkna-sap]

Closes https://github.com/SAP/cloud-sdk-backlog/issues/1291
Related https://github.com/SAP/ai-sdk-js-backlog/issues/466

This PR adds the convenience functions getIasToken() (returning token, refresh token (if available) and expiration) and getIasDestination() (returning a callable destination).

Both accept a service Service | string | ServiceCredentials, unlike transformIasBindingToDestination they allow bare ServiceCredentials (e.g. just clientid, clientsecret and url).

Note: getIasToken() only returns the token as a string, rather than a parsed jwt, because it may not be a jwt.

To support this more flexible usage, existing convenience logic (e.g. app_tid resolution) has been refactored out of transformIasBindingToDestination.

Token caching now relies on the cached token flows added three days ago to @sap/xssec 4.13.0 (getClientCredentialsToken/getJwtBearerToken) instead of the SDK-level IAS client credentials cache to allow for caching closer at lower levels of the implementation.
This means business user tokens are now cached too (https://github.com/SAP/ai-sdk-js-backlog/issues/466).
The useCache toggle is still exposed, but it is currently not possible to change the cache size or implementation via SAP Cloud SDK APIs.

[KavithaSiva]

Initial round of comments.

[KavithaSiva]

[req] resolveIdentityService is unnecessarily async.

[davidkna-sap]

resolveServiceBinding is async, I think this should stay as-is.

[marikaner]

@KavithaSiva I thought the same at first, but I this is useful, so that the second non-async part of the function does not need to be wrapped in a promise.

Example:
Imagine this function (pass in boolean a, if it is true return 1 otherwise 0):

const test = (a: boolean): Promise<any> => (a ? Promise.resolve(1) : 0); # won't work
const test = (a: boolean): Promise<any> => (a ? Promise.resolve(1) : Promise.resolve(0)); # will work
const test = async (a: boolean): Promise<any> => (a ? Promise.resolve(1) : 0); # will work

[KavithaSiva]

[q] Should we also add:
Passing raw ServiceCredentials, Service directly is only recommended for environments where service bindings are unavailable as they hardcode the credentials?

identity string is the best way as the SDK resolves the credentials from the environment automatically.

[KavithaSiva]

Suggested change

	service: ServiceCredentials | string | Service,
	service: ServiceCredentials | 'identity' | Service,

[q] Can't we narrow the type?

[davidkna-sap]

What do you think about putting IasTokenOptions first with service having a sane default?

[marikaner]

Hmm, while I see the point, semantically I think it is better as is.

[marikaner]

I find it a little odd that we have extra functions for the IAS case. I assume you thought about how it could be covered seamlessly in the existing functionality?

[marikaner]

Hmm, while I see the point, semantically I think it is better as is.

[marikaner]

@KavithaSiva I thought the same at first, but I this is useful, so that the second non-async part of the function does not need to be wrapped in a promise.

Example:
Imagine this function (pass in boolean a, if it is true return 1 otherwise 0):

const test = (a: boolean): Promise<any> => (a ? Promise.resolve(1) : 0); # won't work
const test = (a: boolean): Promise<any> => (a ? Promise.resolve(1) : Promise.resolve(0)); # will work
const test = async (a: boolean): Promise<any> => (a ? Promise.resolve(1) : 0); # will work

[marikaner]

[req] Please consider to only disable this for a specific line. Alternatively we could also generally allow it for specific modules in the (local) eslint config.

[davidkna-sap]

I've moved this to the eslint config, the following imports also need this and per-line comments would have required this:

  // eslint-disable-next-line import/no-internal-modules
} from './destination/ias-types';

[marikaner]

If this helps with circular dependencies, maybe it is better in the config even.

[marikaner]

lgtm