SDKS-4816: Fix device client type, update READMEs and e2e apps

.changeset/soft-moose-read.md

@@ -0,0 +1,5 @@
+---
+'@forgerock/device-client': patch
+---
+
+Makes `realm` optional in device profile query

e2e/davinci-app/components/fido.ts

@@ -9,6 +9,7 @@ import type {
   FidoRegistrationCollector,
   FidoAuthenticationCollector,
   Updater,
+  FidoClient,
 } from '@forgerock/davinci-client/types';
 
 export default function fidoComponent(
@@ -17,7 +18,7 @@ export default function fidoComponent(
   updater: Updater<FidoRegistrationCollector | FidoAuthenticationCollector>,
   submitForm: () => Promise<void>,
 ) {
-  const fidoApi = fido();
+  const fidoApi: FidoClient = fido();
   if (collector.type === 'FidoRegistrationCollector') {
     const button = document.createElement('button');
     button.type = 'button';

e2e/device-client-app/src/utils/index.ts

@@ -1,4 +1,5 @@
 import { deviceClient } from '@forgerock/device-client';
+import type { ConfigOptions, DeviceClient } from '@forgerock/device-client/types';
 import {
   CallbackType,
   Config,
@@ -76,11 +77,8 @@ export const LoginAndGetClient = Effect.gen(function* () {
   const un = url.searchParams.get('un') || 'devicetestuser';
   const pw = url.searchParams.get('pw') || 'password';
 
-  const config = {
+  const config: ConfigOptions = {
     realmPath,
-    tree,
-    clientId: 'WebOAuthClient',
-    scope: 'profile email me.read openid',
     serverConfig: {
       baseUrl: amUrl,
       timeout: 3000,
@@ -120,7 +118,7 @@ export const LoginAndGetClient = Effect.gen(function* () {
     Effect.flatMap(() => getTokens),
   );
 
-  const client = deviceClient(config);
+  const client: DeviceClient = deviceClient(config);
   return client;
 });
 

e2e/oidc-app/src/utils/oidc-app.ts

@@ -12,6 +12,7 @@ import type {
   GenericError,
   GetAuthorizationUrlOptions,
   OauthTokens,
+  OidcClient,
   TokenExchangeErrorResponse,
 } from '@forgerock/oidc-client/types';
 
@@ -49,7 +50,7 @@ export async function oidcApp({ config, urlParams }) {
   const state = urlParams.get('state');
   const piflow = urlParams.get('piflow');
 
-  const oidcClient = await oidc({ config });
+  const oidcClient: OidcClient = await oidc({ config });
   if ('error' in oidcClient) {
     displayError(oidcClient);
   }

e2e/protect-app/src/protect-native.ts

@@ -9,6 +9,7 @@
 
 import './style.css';
 import { protect } from '@forgerock/protect';
+import type { Protect } from '@forgerock/protect/types';
 import {
   CallbackType,
   Config,
@@ -23,7 +24,7 @@ import {
   UserManager,
 } from '@forgerock/javascript-sdk';
 
-const protectAPI = protect({ envId: '02fb4743-189a-4bc7-9d6c-a919edfe6447' });
+const protectAPI: Protect = protect({ envId: '02fb4743-189a-4bc7-9d6c-a919edfe6447' });
 const FATAL = 'Fatal';
 
 // Check URL for query parameters

packages/device-client/README.md

@@ -35,7 +35,8 @@ npm install @forgerock/device-client --save
 To configure the `deviceClient`, you need to provide a `ConfigOptions` object that includes the base URL for the server and the realm path.
 
 ```typescript
-import { deviceClient, type ConfigOptions } from '@forgerock/device-client';
+import { deviceClient } from '@forgerock/device-client';
+import type { ConfigOptions } from '@forgerock/device-client/types';
 
 const config: ConfigOptions = {
   serverConfig: {

packages/device-client/src/lib/types/profile-device.types.ts

@@ -5,7 +5,7 @@
  * of the MIT license. See the LICENSE file for details.
  */
 export interface GetProfileDevices {
-  realm: string;
+  realm?: string;
   userId: string;
 }
 

packages/journey-client/README.md

@@ -38,8 +38,7 @@ yarn add @forgerock/journey-client
 ## Quick Start
 
 ```typescript
-import { journey } from '@forgerock/journey-client';
-import { callbackType } from '@forgerock/sdk-types';
+import { journey, callbackType } from '@forgerock/journey-client';
 
 async function authenticateUser() {
   // Initialize the client with wellknown discovery

packages/oidc-client/README.md

@@ -4,24 +4,146 @@ A generic OpenID Connect (OIDC) client library for JavaScript and TypeScript, de
 
 The oidc module follows the [OIDC](https://openid.net/specs/openid-connect-core-1_0.html) specification and provides a simple and easy-to-use API to interact with the OIDC server. It allows you to authenticate, retrieve the access token, revoke the token, and sign out from the OIDC server.
 
+## Installation
+
+```bash
+pnpm add @forgerock/oidc-client
+# or
+npm install @forgerock/oidc-client
+# or
+yarn add @forgerock/oidc-client
+```
+
+## Initialization
+
 ```js
-// Initialize OIDC Client
+import { oidc } from '@forgerock/oidc-client';
+
 const oidcClient = await oidc({
-  /* config */
+  config: {
+    serverConfig: { wellknown: 'https://example.com/.well-known/openid-configuration' },
+    clientId: 'example-client-id',
+    redirectUri: 'https://example-app/redirect-uri',
+    scope: 'openid profile email',
+  },
 });
+```
+
+## API Reference
+
+### authorize
+
+Methods for creating and handling authorization flows.
+
+#### `authorize.url(options?)`
+
+Creates an authorization URL with the provided options or defaults from the configuration.
+
+- **Parameters**: `GetAuthorizationUrlOptions` (optional)
+- **Returns**: `Promise<string | GenericError>` - The authorization URL or an error
+
+```js
+const authUrl = await oidcClient.authorize.url();
+if ('error' in authUrl) {
+  console.error('Authorization URL creation failed:', authUrl.error);
+}
+```
+
+#### `authorize.background(options?)`
+
+Initiates the authorization process in the background, returning the authorization code and state or an error. This method handles the authorization flow without requiring user interaction.
 
-// Authorize API
-const authResponse = await oidcClient.authorize.background(); // Returns code and state if successful, error if not
-const authUrl = await oidcClient.authorize.url(); // Returns Auth URL or error
+- **Parameters**: `GetAuthorizationUrlOptions` (optional)
+- **Returns**: `Promise<AuthorizationSuccess | AuthorizationError>` - An object containing `code` and `state` on success, or error details on failure
+
+```js
+const authResponse = await oidcClient.authorize.background();
+if ('error' in authResponse) {
+  console.error('Authorization failed:', authResponse.error);
+}
+```
 
-// Tokens API
-const newTokens = await oidcClient.token.exchange({
-  /* code, state */
-}); // Returns new tokens or error
-const existingTokens = await oidcClient.token.get(); // Returns existing tokens or error
-const response = await oidcClient.token.revoke(); // Revokes an access token and returns the response or an error
+### token
 
-// User API
-const user = await oidcClient.user.info(); // Returns user object or error
-const logoutResponse = await oidcClient.user.logout(); // Logs the user out and returns the response or an error
+Methods for managing OAuth tokens.
+
+#### `token.exchange(code, state, options?)`
+
+Exchanges an authorization code for tokens using the token endpoint from the wellknown configuration. The tokens are automatically stored in the configured storage.
+
+- **Parameters**:
+  - `code` (string) - The authorization code received from the authorization server
+  - `state` (string) - The state parameter from the authorization URL creation
+  - `options` (`Partial<StorageConfig>`, optional) - Storage configuration for persisting tokens
+- **Returns**: `Promise<OauthTokens | TokenExchangeErrorResponse | GenericError>` - The new tokens or an error
+
+```js
+const tokens = await oidcClient.token.exchange(authCode, authState);
+if ('error' in tokens) {
+  console.error('Token exchange failed:', tokens.error);
+}
+```
+
+#### `token.get(options?)`
+
+Retrieves the current OAuth tokens from storage. Optionally auto-renews tokens if they are expired or if `backgroundRenew` is enabled.
+
+- **Parameters**: `GetTokensOptions` (optional)
+  - `forceRenew` - Force token renewal even if not expired
+  - `backgroundRenew` - Automatically renew expired tokens
+  - `authorizeOptions` - Options for authorization during renewal
+  - `storageOptions` - Storage configuration options
+- **Returns**: `Promise<OauthTokens | TokenExchangeErrorResponse | AuthorizationError | GenericError>` - The tokens or an error
+
+```js
+const tokens = await oidcClient.token.get();
+if ('error' in tokens) {
+  console.error('Token retrieval failed:', tokens.error);
+}
+```
+
+#### `token.revoke()`
+
+Revokes the access token using the revocation endpoint from the wellknown configuration. Requires an access token stored in the configured storage.
+
+- **Parameters**: None
+- **Returns**: `Promise<GenericError | RevokeSuccessResult | RevokeErrorResult>` - Confirmation of revocation or an error
+
+```js
+const response = await oidcClient.token.revoke();
+if ('error' in response) {
+  console.error('Token revocation failed:', response.error);
+}
+```
+
+### user
+
+Methods for user information and session management.
+
+#### `user.info()`
+
+Retrieves user information using the userinfo endpoint from the wellknown configuration. Requires an access token stored in the configured storage.
+
+- **Parameters**: None
+- **Returns**: `Promise<GenericError | UserInfoResponse>` - User information object or an error
+
+```js
+const user = await oidcClient.user.info();
+if ('error' in user) {
+  console.error('Failed to fetch user info:', user.error);
+}
+```
+
+#### `user.logout()`
+
+Logs out the user by revoking tokens and clearing the storage. Uses the end session endpoint from the wellknown configuration.
+
+- **Parameters**: None
+- **Returns**: `Promise<GenericError | LogoutSuccessResult | LogoutErrorResult>` - Confirmation of logout or an error
+
+```js
+const logoutResponse = await oidcClient.user.logout();
+if ('error' in logoutResponse) {
+  console.error('Logout failed:', logoutResponse.error);
+}
 ```