upgrade docs build tools, typescript, and eslint

packages/browser/eslint.config.js

@@ -0,0 +1,22 @@
+const iTwinPlugin = require("@itwin/eslint-plugin");
+
+module.exports = [
+  {
+    files: ["**/*.{ts,tsx}"],
+    ignores: ["**/integration-tests/**"],
+    ...iTwinPlugin.configs.iTwinjsRecommendedConfig,
+  },
+  {
+    files: ["**/*.{ts,tsx}"],
+    ignores: ["**/integration-tests/**"],
+    ...iTwinPlugin.configs.jsdocConfig,
+  },
+  {
+    files: ["**/*.{ts,tsx}"],
+    ignores: ["**/integration-tests/**"],
+    rules: {
+      "no-duplicate-imports": "off",
+      "@typescript-eslint/consistent-type-imports": "error",
+    },
+  },
+];

packages/browser/package.json

@@ -35,9 +35,9 @@
     "oidc-client-ts": "^2.4.0"
   },
   "devDependencies": {
-    "@itwin/build-tools": "^4.0.0-dev.93",
+    "@itwin/build-tools": "^4.6.0-dev.27",
     "@itwin/core-bentley": "^3.7.0",
-    "@itwin/eslint-plugin": "^3.7.0",
+    "@itwin/eslint-plugin": "^4.0.1",
     "@playwright/test": "~1.41.0",
     "@types/chai": "^4.2.22",
     "@types/mocha": "^8.2.3",
@@ -46,26 +46,16 @@
     "buffer": "~6.0.3",
     "chai": "^4.2.22",
     "dotenv": "~16.0.3",
-    "eslint": "^7.32.0",
+    "eslint": "^8.56.0",
     "mocha": "^8.2.3",
     "nyc": "^15.1.0",
     "parcel": "~2.12.0",
     "process": "~0.11.10",
     "rimraf": "^3.0.2",
     "sinon": "^15.0.1",
-    "typescript": "~5.0.2"
+    "typescript": "~5.3.3"
   },
   "peerDependencies": {
     "@itwin/core-bentley": "^3.3.0 || ^4.0.0"
-  },
-  "eslintConfig": {
-    "plugins": [
-      "@itwin"
-    ],
-    "extends": "plugin:@itwin/itwinjs-recommended",
-    "rules": {
-      "no-duplicate-imports": "off",
-      "@typescript-eslint/consistent-type-imports": "error"
-    }
   }
 }

packages/browser/src/Client.ts

@@ -76,9 +76,6 @@ export class BrowserAuthorizationClient implements AuthorizationClient {
 
   /**
    * Merges the basic and advanced settings into a single configuration object consumable by the internal userManager.
-   * @param basicSettings
-   * @param advancedSettings
-   * @returns a promise resolving to UserManagerSettings
    */
   protected async getUserManagerSettings(basicSettings: BrowserAuthorizationClientConfiguration, advancedSettings?: UserManagerSettings): Promise<UserManagerSettings> {
     let userManagerSettings: UserManagerSettings = {
@@ -104,7 +101,6 @@ export class BrowserAuthorizationClient implements AuthorizationClient {
 
   /**
    * Creates the internal user manager and binds all relevant events to their respective callback function.
-   * @param settings
    */
   protected createUserManager(settings: UserManagerSettings): UserManager {
     const userManager = new UserManager(settings);
@@ -434,7 +430,7 @@ export class BrowserAuthorizationClient implements AuthorizationClient {
 
   private static loadSettingsFromStorage(
     client: BrowserAuthorizationClient,
-    store: Storage
+    store: Storage,
   ) {
     const url = new URL(window.location.href);
     const nonce = url.searchParams.get("state");

packages/browser/src/test/BrowserAuthorizationClient.test.ts

@@ -43,7 +43,7 @@ describe("BrowserAuthorizationClient", () => {
       assert.equal(settings.redirectUri, "test_redirectUri");
       assert.equal(
         settings.postSignoutRedirectUri,
-        "test_postSignoutRedirectUri"
+        "test_postSignoutRedirectUri",
       );
       assert.equal(settings.scope, "test_scope");
       assert.equal(settings.responseType, "test_responseType");

packages/browser/src/types.ts

@@ -44,14 +44,7 @@ export interface BrowserAuthorizationClientConfiguration
   /** A space-delimited collection of individual access claims specified by the authority. The user must consent to all specified scopes in order to grant authorization */
   readonly scope: string;
   /** The mechanism (or authentication flow) used to acquire auth information from the user through the authority */
-  readonly responseType?:
-  | "code"
-  | "id_token"
-  | "id_token token"
-  | "code id_token"
-  | "code token"
-  | "code id_token token"
-  | string;
+  readonly responseType?: string;
   /** if true, do NOT attempt a silent signIn on startup of the application */
   readonly noSilentSignInOnAppStartup?: boolean;
   /** The redirect URL used for silent sign in and renew. If not provided, will default to redirectUri. */
@@ -66,9 +59,12 @@ export interface BrowserAuthorizationClientConfiguration
  */
 export interface BrowserAuthorizationClientRequestOptions {
   /** The required action demanded of the user before the authentication request can succeed */
-  prompt?: "none" | "login" | "consent" | "select_account" | string;
+  prompt?: string;
 }
 
+/**
+ * Represents the settings stored in storage.
+ */
 export interface SettingsInStorage {
   id: string; // nonce/state
   authority: string;

packages/browser/src/utils.ts

@@ -12,8 +12,6 @@
  * A prefix will be prepended based on the value of the IMJS_URL_PREFIX environment variable.
  * The prefix "dev-" will automatically be converted to "qa-".
  * @deprecated in 1.1.x Please set the authority in `BrowserAuthorizationClientConfiguration` configuration object.
- * @param authorityUrl
- * @returns
  */
 export function getImsAuthority(): string {
   try {

packages/electron/README.md

@@ -12,7 +12,7 @@ The OAuth2.0 workflow used in this package is Authorization Code + PKCE, for mor
 
 The package is broken into two main classes `ElectronMainAuthorization` and `ElectronRendererAuthorization` that communicate via Electron's IPC between the [main](https://www.electronjs.org/docs/latest/api/ipc-main) and [renderer](https://www.electronjs.org/docs/latest/api/ipc-renderer) process, respectively. The IPC channel is used to pass the login and access token information and handle refreshing the token when necessary.
 
-During initialization, this package will start an express.js loopback server. The port is 3000 by default and can be adjusted by setting the `redirectUrl` with url and port
+During initialization, this package will start an express.js loopback server. The port is 3000 by default and can be adjusted by setting the `_redirectUris` with url and port
 
 ## Usage
 
@@ -40,6 +40,7 @@ const client = new ElectronMainAuthorization({
 
 await client.signIn(); // sign in from the main process
 ```
+
 <blockquote> If your app has its own directory to store config files, you can override the default path the refresh token is stored by specifying an optional field in the constructor object, like so:
 
 ```typescript
@@ -48,6 +49,7 @@ new ElectronMainAuthorization({
   tokenStorePath: yourOwnDirectoryAbsolutePath
 })
 ```
+
 </blockquote>
 2. Setup Renderer Process
 
@@ -85,7 +87,7 @@ If keytar is being used in a headless environment additional steps need to be ta
 
 Users will then need to start a dbus session and create a keyring password by running `dbus-run-session -- sh` and then creating a keyring with `echo 'keyringPassword' | gnome-keyring-daemon -r -d --unlock`. Then simply start up the application like normal while in the dbus session: `npm run start`. If running within a Docker container, make sure to add the `--privileged` argument when running the container.
 
-### API
+## API
 
 `ElectronMainAuthorization`
 
@@ -109,3 +111,26 @@ Users will then need to start a dbus session and create a keyring password by ru
 | `getAccessToken`       | returns a token if available, otherwise calls `refreshToken` | `Function` | `Promise<AccessToken>` |
 | `hasSignedIn`          | Whether or not the user has _ever_ signed in                 | `getter`   | `boolean`              |
 | `isAuthorized`         | Whether the user is signed in and not expired                | `getter`   | `boolean`              |
+
+### `new ElectronMainAuthorization(options)` - options
+
+| Property                | Type                               | Description                                                                                                                              |
+| ----------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `issuerUrl`             | `string` (optional)                | The OAuth token issuer URL. Defaults to Bentley's auth production URL if undefined.                                                      |
+| `redirectUris`          | `string[]`                         | List of redirect URIs available for use in the OAuth authorization flow. See note below:                                                 |
+| `clientId`              | `string`                           | Client application's identifier as registered with the OIDC/OAuth2 provider.                                                             |
+| `scopes`                | `string`                           | List of space separated scopes to request access to various resources.                                                                   |
+| `expiryBuffer`          | `number` (optional)                | Time in seconds that's used as a buffer to check the token for validity/expiry.                                                          |
+| `ipcSocket`             | `IpcSocketBackend` (optional)      | Optional custom implementation of `IpcSocketBackend` to use for IPC communication with the Frontend counterpart of authorization client. |
+| `authenticationOptions` | `AuthenticationOptions` (optional) | Additional options to use for every OIDC authentication request made by `ElectronMainAuthorization`.                                     |
+| `tokenStorePath`        | `string` (optional)                | Directory path that overrides where the refresh token is stored.                                                                         |
+
+### RedirectUris
+
+The `redirectUris` property is an array of strings that represent the URIs that the authorization server can redirect to after the user has authenticated. The URIs must be in the format `http(s)://localhost:port` where `port` is the port number that the ElectronMainAuthorization instance will listen on. The default port is 3000.
+
+- In the case of a port collision, it is recommended to use multiple (e.g. three) redirect URIs with different ports.
+- A decent strategy for choosing ports for your application is: `3|4|5{GPR_ID}`. For example (GPR_ID used here is 1234):
+- `http://localhost:31234/signin-callback`
+- `http://localhost:41234/signin-callback`
+- `http://localhost:51234/signin-callback`

packages/electron/eslint.config.js

@@ -0,0 +1,19 @@
+const iTwinPlugin = require("@itwin/eslint-plugin");
+
+module.exports = [
+  {
+    files: ["**/*.{ts,tsx}"],
+    ...iTwinPlugin.configs.iTwinjsRecommendedConfig,
+  },
+  {
+    files: ["**/*.{ts,tsx}"],
+    ...iTwinPlugin.configs.jsdocConfig,
+  },
+  {
+    files: ["**/*.{ts,tsx}"],
+    rules: {
+      "no-duplicate-imports": "off",
+      "@typescript-eslint/consistent-type-imports": "error",
+    },
+  },
+];

packages/electron/package.json

@@ -47,9 +47,9 @@
     "username": "^5.1.0"
   },
   "devDependencies": {
-    "@itwin/build-tools": "^4.0.6",
+    "@itwin/build-tools": "^4.6.0-dev.27",
     "@itwin/core-bentley": "^3.7.0",
-    "@itwin/eslint-plugin": "^3.3.0",
+    "@itwin/eslint-plugin": "^4.0.1",
     "@playwright/test": "~1.41.0",
     "@types/chai": "^4.2.22",
     "@types/chai-as-promised": "^7.1.1",
@@ -61,7 +61,7 @@
     "cpx2": "^5.0.0",
     "dotenv": "~16.0.3",
     "electron": "^30.0.0",
-    "eslint": "^7.32.0",
+    "eslint": "^8.56.0",
     "mocha": "^8.2.3",
     "nyc": "^15.1.0",
     "parcel": "~2.9.3",
@@ -70,20 +70,10 @@
     "rimraf": "^3.0.2",
     "sinon": "^15.0.1",
     "source-map-support": "^0.5.9",
-    "typescript": "~5.0.2"
+    "typescript": "~5.3.3"
   },
   "peerDependencies": {
     "@itwin/core-bentley": "^3.3.0 || ^4.0.0",
     "electron": ">=23.0.0 <31.0.0"
-  },
-  "eslintConfig": {
-    "plugins": [
-      "@itwin"
-    ],
-    "extends": "plugin:@itwin/itwinjs-recommended",
-    "rules": {
-      "no-duplicate-imports": "off",
-      "@typescript-eslint/consistent-type-imports": "error"
-    }
   }
 }

packages/electron/src/integration-test/helpers/TestHelper.ts

@@ -6,6 +6,9 @@
 import type { Page } from "@playwright/test";
 import type { SignInOptions } from "../types";
 
+/**
+ * Helper class for tests
+ */
 export class TestHelper {
   constructor(private _signInOptions: SignInOptions) { }
 
@@ -36,7 +39,7 @@ export class TestHelper {
 
   public async signIn(page: Page, url: string) {
     await page.goto(url);
-    await page.waitForSelector("#identifierInput", {timeout: 5000});
+    await page.waitForSelector("#identifierInput", { timeout: 5000 });
     await page.getByLabel("Email address").fill(this._signInOptions.email);
     await page.getByLabel("Email address").press("Enter");
     await page.getByLabel("Password").fill(this._signInOptions.password);

packages/electron/src/integration-test/helpers/loadConfig.ts

@@ -5,6 +5,9 @@
 
 import { config } from "dotenv";
 
+/**
+ * Load configuration from environment variables.
+ */
 export function loadConfig() {
   config();
 
@@ -14,7 +17,7 @@ export function loadConfig() {
     !process.env.IMJS_TEST_REGULAR_USER_PASSWORD
   ) {
     throw new Error(
-      "Please expose IMJS_TEST_ELECTRON_CLIENT_ID, IMJS_TEST_REGULAR_USER_NAME and IMJS_TEST_REGULAR_USER_PASSWORD as env variables"
+      "Please expose IMJS_TEST_ELECTRON_CLIENT_ID, IMJS_TEST_REGULAR_USER_NAME and IMJS_TEST_REGULAR_USER_PASSWORD as env variables",
     );
   }
 

packages/electron/src/integration-test/types.ts

@@ -3,6 +3,9 @@
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 
+/**
+ * Options for signing in.
+ */
 export interface SignInOptions {
   clientId: string;
   email: string;