Deprecate AccessTokenAdapter.toAuthorizationCallback(string)

clients/imodels-client-authoring/README.md

@@ -19,9 +19,7 @@ Please see the [list of key methods and types](../../docs/IModelsClientAuthoring
 ```typescript
 const iModelIterator: EntityListIterator<MinimalIModel> =
   iModelsClient.iModels.getMinimalList({
-    authorization: AccessTokenAdapter.toAuthorizationCallback(
-      await IModelHost.getAccessToken()
-    ),
+    authorization: AccessTokenAdapter.toAuthorizationCallback(IModelHost.getAccessToken),
     urlParams: {
       projectId: "8a1fcd73-8c23-460d-a392-8b4afc00affc",
     },

clients/imodels-client-management/README.md

@@ -15,9 +15,7 @@ Please see the [list of key methods and types](../../docs/IModelsClientManagemen
 ```typescript
 const iModelIterator: EntityListIterator<MinimalIModel> =
   iModelsClient.iModels.getMinimalList({
-    authorization: AccessTokenAdapter.toAuthorizationCallback(
-      await IModelApp.getAccessToken()
-    ),
+    authorization: AccessTokenAdapter.toAuthorizationCallback(IModelApp.getAccessToken),
     urlParams: {
       projectId: "8a1fcd73-8c23-460d-a392-8b4afc00affc",
     },

common/changes/@itwin/imodels-access-backend/accessTokenAdapter_2024-11-20-10-38.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/imodels-access-backend",
+      "comment": "Remove use of deprecated AccessTokenAdapter.toAuthorizationCallback",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@itwin/imodels-access-backend"
+}

common/changes/@itwin/imodels-access-common/accessTokenAdapter_2024-11-20-10-38.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/imodels-access-common",
+      "comment": "Deprecate AccessTokenAdapter.toAuthorizationCallback",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@itwin/imodels-access-common"
+}

common/changes/@itwin/imodels-access-frontend/accessTokenAdapter_2024-11-20-10-38.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/imodels-access-frontend",
+      "comment": "Remove use of deprecated AccessTokenAdapter.toAuthorizationCallback",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@itwin/imodels-access-frontend"
+}

common/changes/@itwin/imodels-client-authoring/accessTokenAdapter_2024-11-20-10-38.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/imodels-client-authoring",
+      "comment": "Update documentation",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@itwin/imodels-client-authoring"
+}

common/changes/@itwin/imodels-client-management/accessTokenAdapter_2024-11-20-10-38.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/imodels-client-management",
+      "comment": "Update documentation",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@itwin/imodels-client-management"
+}

docs/IModelsClientAuthoring.md

@@ -47,7 +47,7 @@ Since the `@itwin/imodels-client-authoring` package extends the `@itwin/imodels-
 `IModelsClient` expects the authorization info to be passed in a form of an asynchronous callback that returns authorization info. It is a common use case to consume `IModelsClient` in iTwin.js platform based applications which use `IModelApp.getAccessToken` or `IModelHost.getAccessToken` to get the authorization header value returned as a string. The authorization header value specifies the schema and access token e.g. `Bearer ey...`. To convert this value into the format that `IModelsClients` expect users can use `AccessTokenAdapter` class which is exported by both [`@itwin/imodels-access-frontend`](../itwin-platform-access/imodels-access-frontend/src/interface-adapters/AccessTokenAdapter.ts) and [`@itwin/imodels-access-backend`](../itwin-platform-access/imodels-access-backend/src/interface-adapters/AccessTokenAdapter.ts) packages.
 ```typescript
 const iModelIterator: EntityListIterator<MinimalIModel> = iModelsClient.iModels.getMinimalList({
-  authorization: AccessTokenAdapter.toAuthorizationCallback(await IModelHost.getAccessToken()),
+  authorization: AccessTokenAdapter.toAuthorizationCallback(IModelHost.getAccessToken),
   urlParams: {
     iTwinId: "8a1fcd73-8c23-460d-a392-8b4afc00affc"
   }
@@ -78,4 +78,4 @@ async function createIModelFromBaselineFile(): Promise<void> {
 async function getAuthorization(): Promise<Authorization> {
   return { scheme: "Bearer", token: "ey..." };
 }
-```
+```

docs/IModelsClientManagement.md

@@ -58,7 +58,7 @@
 `IModelsClient` expects the authorization info to be passed in a form of an asynchronous callback that returns authorization info. It is a common use case to consume `IModelsClient` in iTwin.js platform based applications which use `IModelApp.getAccessToken` or `IModelHost.getAccessToken` to get the authorization header value returned as a string. The authorization header value specifies the schema and access token e.g. `Bearer ey...`. To convert this value into the format that `IModelsClients` expect users can use `AccessTokenAdapter` class which is exported by both [`@itwin/imodels-access-frontend`](../itwin-platform-access/imodels-access-frontend/src/interface-adapters/AccessTokenAdapter.ts) and [`@itwin/imodels-access-backend`](../itwin-platform-access/imodels-access-backend/src/interface-adapters/AccessTokenAdapter.ts) packages.
 ```typescript
 const iModelIterator: EntityListIterator<MinimalIModel> = iModelsClient.iModels.getMinimalList({
-  authorization: AccessTokenAdapter.toAuthorizationCallback(await IModelApp.getAccessToken()),
+  authorization: AccessTokenAdapter.toAuthorizationCallback(IModelApp.getAccessToken),
   urlParams: {
     iTwinId: "8a1fcd73-8c23-460d-a392-8b4afc00affc"
   }

itwin-platform-access/imodels-access-backend/src/BackendIModelsAccess.ts

@@ -9,7 +9,7 @@ import {
   ChangesetRangeArg, CheckpointArg, CheckpointProps, CreateNewIModelProps, DownloadChangesetArg, DownloadChangesetRangeArg,
   IModelDb, IModelHost, IModelIdArg, IModelJsFs, IModelJsNative, IModelNameArg, ITwinIdArg, KnownLocations, LockMap, LockProps, SnapshotDb, TokenArg, V2CheckpointAccessProps
 } from "@itwin/core-backend";
-import { BriefcaseStatus, Guid, GuidString, Logger, OpenMode, StopWatch } from "@itwin/core-bentley";
+import { AccessToken, BriefcaseStatus, Guid, GuidString, Logger, OpenMode, StopWatch } from "@itwin/core-bentley";
 import {
   BriefcaseId, BriefcaseIdValue, ChangesetFileProps, ChangesetIndex, ChangesetIndexAndId, ChangesetProps, IModelError,
   IModelVersion
@@ -418,19 +418,16 @@ export class BackendIModelsAccess implements BackendHubAccess {
 
   private getAuthorizationParam(tokenArg: TokenArg): AuthorizationParam {
     const authorizationCallback: AuthorizationCallback = tokenArg.accessToken
-      ? AccessTokenAdapter.toAuthorizationCallback(tokenArg.accessToken)
-      : this.getAuthorizationCallbackFromIModelHost();
+      ? this.getAuthorizationCallbackFromToken(tokenArg.accessToken)
+      : AccessTokenAdapter.toAuthorizationCallback(IModelHost.getAccessToken);
 
     return {
       authorization: authorizationCallback
     };
   }
 
-  private getAuthorizationCallbackFromIModelHost(): AuthorizationCallback {
-    return async () => {
-      const token = await IModelHost.getAccessToken();
-      return AccessTokenAdapter.toAuthorization(token);
-    };
+  private getAuthorizationCallbackFromToken(accessToken: AccessToken): AuthorizationCallback {
+    return async () => AccessTokenAdapter.toAuthorization(accessToken);
   }
 
   private setLockLevelToNone(lockedObjectsForBriefcase: LockedObjects[]): void {

itwin-platform-access/imodels-access-common/src/AccessTokenAdapter.ts

@@ -19,8 +19,21 @@ export class AccessTokenAdapter {
     };
   }
 
-  public static toAuthorizationCallback(accessToken: AccessToken): AuthorizationCallback {
-    const authorization: Authorization = AccessTokenAdapter.toAuthorization(accessToken);
-    return async () => authorization;
+  /** @deprecated in 5.2. Use {@link toAuthorizationCallback} with a callback parameter instead. */
+  public static toAuthorizationCallback(accessToken: AccessToken): AuthorizationCallback;
+
+  // eslint-disable-next-line @typescript-eslint/unified-signatures
+  public static toAuthorizationCallback(getAccessToken: () => Promise<AccessToken>): AuthorizationCallback;
+
+  public static toAuthorizationCallback(accessToken: AccessToken | (() => Promise<AccessToken>)): AuthorizationCallback {
+    if (typeof accessToken === "function") {
+      return async () => {
+        const token = await accessToken();
+
+        return AccessTokenAdapter.toAuthorization(token);
+      };
+    } else {
+      return async () => AccessTokenAdapter.toAuthorization(accessToken);
+    }
   }
 }

itwin-platform-access/imodels-access-frontend/src/FrontendIModelsAccess.ts

@@ -76,22 +76,15 @@ export class FrontendIModelsAccess implements FrontendHubAccess {
 
   private getIModelScopedOperationParams(arg: IModelIdArg): IModelScopedOperationParams {
     const authorizationCallback: AuthorizationCallback = arg.accessToken
-      ? AccessTokenAdapter.toAuthorizationCallback(arg.accessToken)
-      : this.getAuthorizationCallbackFromIModelApp();
+      ? async () => AccessTokenAdapter.toAuthorization(arg.accessToken)
+      : AccessTokenAdapter.toAuthorizationCallback(IModelApp.getAccessToken);
 
     return {
       authorization: authorizationCallback,
       iModelId: arg.iModelId
     };
   }
 
-  private getAuthorizationCallbackFromIModelApp(): AuthorizationCallback {
-    return async () => {
-      const token = await IModelApp.getAccessToken();
-      return AccessTokenAdapter.toAuthorization(token);
-    };
-  }
-
   private async getChangesetFromLatestNamedVersion(arg: IModelIdArg): Promise<ChangesetIndexAndId> {
     const getNamedVersionListParams: GetNamedVersionListParams = {
       ...this.getIModelScopedOperationParams(arg),