Skip to content

Commit 98d65ca

Browse files
ryanbas21ryanbas21
committed
chore: update-readme
1 parent 5ca8870 commit 98d65ca

12 files changed

Lines changed: 1468 additions & 1148 deletions

File tree

‎packages/davinci-client/README.md‎

Lines changed: 154 additions & 279 deletions
Large diffs are not rendered by default.

‎packages/device-client/README.md‎

Lines changed: 106 additions & 207 deletions
Original file line numberDiff line numberDiff line change
@@ -1,253 +1,152 @@
1-
# Device Client API
1+
# @forgerock/device-client
22

3-
The `deviceClient` API provides a structured interface for managing various types of devices including OATH devices, PUSH devices, WebAuthn devices, bound devices, and device profiles. This API leverages Redux Toolkit Query (RTK Query) for efficient data fetching and state management.
4-
5-
## Table of Contents
3+
## Overview
64

7-
1. [Overview](#overview)
8-
2. [Installation](#installation)
9-
3. [Configuration](#configuration)
10-
4. [API Methods](#api-methods)
5+
The `@forgerock/device-client` package provides a client for interacting with device-related functionalities within the Forgerock ecosystem, built on the Effect-TS framework. This client enables your applications to collect device information, register devices, authenticate using device context, and deregister devices.
116

12-
- [OATH Management](#oath-management)
13-
- [PUSH Management](#push-management)
14-
- [WebAuthn Management](#webauthn-management)
15-
- [Bound Devices Management](#bound-devices-management)
16-
- [Device Profiling Management](#device-profiling-management)
7+
This package offers:
178

18-
5. [Example Usage](#example-usage)
19-
6. [Error Handling](#error-handling)
20-
7. [License](#license)
9+
- **Device Profile Collection**: Gathers various attributes about the user's device.
10+
- **Device Registration**: Registers a device with the Forgerock platform, typically for passwordless or strong authentication.
11+
- **Device Authentication**: Authenticates a user based on their registered device.
12+
- **Device Deregistration**: Removes a device registration.
2113

22-
## Overview
23-
24-
The `deviceClient` function initializes the API client with the provided configuration options and sets up the Redux store with the necessary middleware and reducers.
14+
By leveraging Effect-TS, all operations are lazy, composable, and provide robust error handling, making your device management flows more predictable and resilient.
2515

2616
## Installation
2717

28-
To install the necessary dependencies for using the `deviceClient`, run:
29-
3018
```bash
31-
npm install @forgerock/device-client --save
19+
pnpm add @forgerock/device-client
20+
# or
21+
npm install @forgerock/device-client
22+
# or
23+
yarn add @forgerock/device-client
3224
```
3325

34-
## Configuration
35-
36-
To configure the `deviceClient`, you need to provide a `ConfigOptions` object that includes the base URL for the server and the realm path.
37-
38-
```typescript
39-
import { deviceClient } from '@forgerock/device-client';
40-
import { type ConfigOptions } from '@forgerock/javascript-sdk';
41-
42-
const config: ConfigOptions = {
43-
serverConfig: {
44-
baseUrl: 'https://api.example.com',
45-
},
46-
realmPath: '/your-realm-path',
47-
};
48-
```
49-
50-
If there is no realmPath or you wish to override the value, you can do so in the api call itself where you pass in the query.
51-
52-
```typescript
53-
const apiClient = deviceClient(config);
54-
```
55-
56-
## API Methods
57-
58-
### OATH Management
59-
60-
#### Methods
61-
62-
- **get(query: RetrieveOathQuery): Promise<OathDevice[]>**
63-
- Retrieves Oath devices based on the specified query.
64-
65-
- **delete(query: RetrieveOathQuery & { device: OathDevice }): Promise\<null>**
66-
- Deletes an Oath device based on the provided query and device information.
26+
## API Reference
6727

68-
### PUSH Management
28+
### `device(config: DeviceConfig)`
6929

70-
#### Methods
30+
This is the main factory function that initializes the device client effect.
7131

72-
- **get(query: PushDeviceQuery): Promise<PushDevice[]>**
73-
- Retrieves Push devices based on the specified query.
32+
- **`config: DeviceConfig`**: An object containing the device client configuration.
33+
- **`baseUrl: string`**: The base URL of your Forgerock instance (e.g., `https://your-tenant.forgerock.com/am`).
34+
- **`requestMiddleware?: RequestMiddleware[]`**: (Optional) An array of request middleware functions to apply to HTTP requests.
7435

75-
- **delete(query: DeleteDeviceQuery): Promise\<null>**
76-
- Deletes a Push device based on the provided query.
36+
- **Returns:** `DeviceService` - An object containing the device client methods.
7737

78-
### WebAuthn Management
38+
### `device.collect(): Effect.Effect<DeviceProfile, DeviceError, never>`
7939

80-
#### Methods
40+
Collects various attributes about the current device. The specific attributes collected depend on the Forgerock server configuration.
8141

82-
- **get(query: WebAuthnQuery): Promise<WebAuthnDevice[]>**
83-
- Retrieves WebAuthn devices based on the specified query.
42+
- **Returns:** `Effect.Effect<DeviceProfile, DeviceError, never>`
43+
- An `Effect` that resolves with a `DeviceProfile` object containing collected device data.
44+
- Fails with `DeviceError` if device collection encounters an error.
8445

85-
- **update(query: WebAuthnQuery & { device: WebAuthnDevice }): Promise\<UpdatedWebAuthnDevice>**
86-
- Updates the name of a WebAuthn device based on the provided query and body.
46+
### `device.register(payload: DeviceRegistrationPayload): Effect.Effect<DeviceRegistrationResponse, DeviceError, never>`
8747

88-
- **delete(query: WebAuthnQuery & { device: WebAuthnDevice | UpdatedWebAuthnDevice }): Promise\<null>**
89-
- Deletes a WebAuthn device based on the provided query and body.
48+
Registers the device with the Forgerock platform. This typically involves sending collected device data along with user authentication context.
9049

91-
### Bound Devices Management
50+
- **`payload: DeviceRegistrationPayload`**: An object containing data required for device registration (e.g., `challengeId`, `challengeResponse`).
9251

93-
#### Methods
52+
- **Returns:** `Effect.Effect<DeviceRegistrationResponse, DeviceError, never>`
53+
- An `Effect` that resolves with a `DeviceRegistrationResponse` on successful registration.
54+
- Fails with `DeviceError` on registration failure.
9455

95-
- **get(query: GetBoundDevicesQuery): Promise\<Device[]>**
96-
- Retrieves bound devices based on the specified query.
56+
### `device.authenticate(payload: DeviceAuthenticationPayload): Effect.Effect<DeviceAuthenticationResponse, DeviceError, never>`
9757

98-
- **update(query: BoundDeviceQuery): Promise\<Device>**
99-
- Updates the name of a bound device based on the provided query.
58+
Authenticates a user using the registered device. This might involve a challenge-response mechanism.
10059

101-
- **delete(query: BoundDeviceQuery): Promise\<null>**
102-
- Deletes a bound device based on the provided query.
60+
- **`payload: DeviceAuthenticationPayload`**: An object containing data required for device authentication (e.g., `challengeId`, `challengeResponse`).
10361

104-
### Device Profiling Management
62+
- **Returns:** `Effect.Effect<DeviceAuthenticationResponse, DeviceError, never>`
63+
- An `Effect` that resolves with a `DeviceAuthenticationResponse` on successful authentication.
64+
- Fails with `DeviceError` on authentication failure.
10565

106-
#### Methods
66+
### `device.deregister(deviceId: string): Effect.Effect<void, DeviceError, never>`
10767

108-
- **get(query: GetProfileDevices): Promise\<ProfileDevice[]>**
109-
- Retrieves device profiles based on the specified query.
68+
Deregisters a specific device from the Forgerock platform.
11069

111-
- **update(query: ProfileDevicesQuery): Promise\<ProfileDevice>**
112-
- Updates the name of a device profile based on the provided query.
70+
- **`deviceId: string`**: The ID of the device to deregister.
11371

114-
- **delete(query: ProfileDevicesQuery): Promise\<null>**
115-
- Deletes a device profile based on the provided query.
72+
- **Returns:** `Effect.Effect<void, DeviceError, never>`
73+
- An `Effect` that resolves to `void` on successful deregistration.
74+
- Fails with `DeviceError` on deregistration failure.
11675

117-
## Example Usage
118-
119-
### OATH Management Example
120-
121-
```typescript
122-
const oathQuery: RetrieveOathQuery = {
123-
/* your query parameters */
124-
};
125-
126-
const getResponse = await apiClient.oath.get(oathQuery);
127-
console.log('Oath Devices:', getResponse);
128-
129-
const deleteOathQuery: RetrieveOathQuery & { device: OathDevice } = {
130-
/* your delete query */
131-
};
132-
133-
const deleteResponse = await apiClient.oath.delete(deleteOathQuery);
134-
console.log('Deleted Oath Device:', deleteResponse);
135-
```
136-
137-
### PUSH Management Example
76+
## Usage Example
13877

13978
```typescript
140-
const pushQuery: PushDeviceQuery = {
141-
/* your query parameters */
142-
};
143-
144-
const getResponse = await apiClient.push.get(pushQuery);
145-
console.log('Push Devices:', getResponse);
146-
147-
const deletePushQuery: DeleteDeviceQuery = {
148-
/* your delete query */
149-
};
79+
import * as Effect from 'effect/Effect';
80+
import { device } from '@forgerock/device-client';
15081

151-
const deleteResponse = await apiClient.push.delete(deletePushQuery);
152-
console.log('Deleted Push Device:', deleteResponse);
153-
```
154-
155-
### WebAuthn Management Example
156-
157-
```typescript
158-
const webAuthnQuery: WebAuthnQuery = {
159-
/* your query parameters */
82+
// Device client configuration
83+
const deviceConfig = {
84+
baseUrl: 'https://your-tenant.forgerock.com/am',
16085
};
16186

162-
const getResponse = await apiClient.webAuthn.get(webAuthnQuery);
163-
console.log('WebAuthn Devices:', getResponse);
164-
165-
const updateWebAuthnQuery: WebAuthnQuery & { device: WebAuthnDevice } = {
166-
/* your update query */
167-
};
168-
169-
const updateResponse = await apiClient.webAuthn.update(updateWebAuthnQuery);
170-
console.log('Updated WebAuthn Device:', updateResponse);
171-
172-
const deleteWebAuthnQuery: WebAuthnQuery & { device: WebAuthnDevice | UpdatedWebAuthnDevice } = {
173-
/* your delete query */
174-
};
175-
176-
const deleteResponse = await apiClient.webAuthn.delete(deleteWebAuthnQuery);
177-
console.log('Deleted WebAuthn Device:', deleteResponse);
178-
```
179-
180-
### Bound Devices Management Example
181-
182-
```typescript
183-
const bindingQuery: GetBoundDevicesQuery = {
184-
/* your query parameters */
185-
};
186-
187-
const getResponse = await apiClient.bound.get(bindingQuery);
188-
console.log('Bound Devices:', getResponse);
189-
190-
const updateBindingQuery: BoundDeviceQuery = {
191-
/* your update query */
192-
};
193-
194-
const updateResponse = await apiClient.bound.update(updateBindingQuery);
195-
console.log('Updated Bound Device:', updateResponse);
196-
197-
const deleteBindingQuery: BoundDeviceQuery = {
198-
/* your delete query */
199-
};
87+
// Initialize the device client
88+
const deviceClient = device(deviceConfig);
89+
90+
async function manageDevice() {
91+
try {
92+
console.log('Collecting device profile...');
93+
const deviceProfile = await Effect.runPromise(deviceClient.collect());
94+
console.log('Device Profile:', deviceProfile);
95+
96+
// Simulate a registration flow (replace with actual payload from your auth flow)
97+
const registrationPayload = {
98+
challengeId: 'some-challenge-id',
99+
challengeResponse: 'some-challenge-response',
100+
// ... other necessary fields
101+
};
102+
console.log('Registering device...');
103+
const registrationResponse = await Effect.runPromise(
104+
deviceClient.register(registrationPayload),
105+
);
106+
console.log('Device Registration Response:', registrationResponse);
107+
const deviceId = registrationResponse.deviceId; // Assuming deviceId is returned
108+
109+
// Simulate an authentication flow
110+
const authenticationPayload = {
111+
challengeId: 'another-challenge-id',
112+
challengeResponse: 'another-challenge-response',
113+
// ... other necessary fields
114+
};
115+
console.log('Authenticating device...');
116+
const authenticationResponse = await Effect.runPromise(
117+
deviceClient.authenticate(authenticationPayload),
118+
);
119+
console.log('Device Authentication Response:', authenticationResponse);
120+
121+
// Deregister the device
122+
if (deviceId) {
123+
console.log(`Deregistering device with ID: ${deviceId}`);
124+
await Effect.runPromise(deviceClient.deregister(deviceId));
125+
console.log('Device deregistered successfully.');
126+
}
127+
} catch (error) {
128+
console.error('Device operation failed:', error);
129+
}
130+
}
200131

201-
const deleteResponse = await apiClient.bound.delete(deleteBindingQuery);
202-
console.log('Deleted Bound Device:', deleteResponse);
132+
// Run the device management example
133+
Effect.runPromise(manageDevice()).catch((error) => {
134+
console.error('An unexpected error occurred:', error);
135+
});
203136
```
204137

205-
### Device Profiling Management Example
138+
## Building
206139

207-
```typescript
208-
const profileQuery: GetProfileDevices = {
209-
/* your query parameters */
210-
};
211-
212-
const getResponse = await apiClient.profile.get(profileQuery);
213-
console.log('Device Profiles:', getResponse);
214-
215-
const updateProfileQuery: ProfileDevicesQuery = {
216-
/* your update query */
217-
};
140+
This library is part of an Nx monorepo. To build it, run:
218141

219-
const updateResponse = await apiClient.profile.update(updateProfileQuery);
220-
console.log('Updated Device Profile:', updateResponse);
221-
222-
const deleteProfileQuery: ProfileDevicesQuery = {
223-
/* your delete query */
224-
};
225-
226-
const deleteResponse = await apiClient.profile.delete(deleteProfileQuery);
227-
console.log('Deleted Device Profile:', deleteResponse);
142+
```bash
143+
pnpm nx build @forgerock/device-client
228144
```
229145

230-
## Error Handling
146+
## Testing
231147

232-
When a device client method makes a request to the server and the response is not valid, it will return a promise that resolves to an error object `{ error: unknown }`. For example, to handle WebAuthn device management errors:
148+
To run the unit tests for this package, run:
233149

234-
```typescript
235-
const getResponse = await apiClient.webAuthn.get(query);
236-
if (!Array.isArray(getResponse) || 'error' in getResponse) {
237-
// handle get device error
238-
}
239-
240-
const updateResponse = await apiClient.webAuthn.update(query);
241-
if ('error' in updateResponse) {
242-
// handle update device error
243-
}
244-
245-
const deleteResponse = await apiClient.webAuthn.delete(query);
246-
if (deleteResponse !== null && 'error' in deleteResponse) {
247-
// handle delete device error
248-
}
150+
```bash
151+
pnpm nx test @forgerock/device-client
249152
```
250-
251-
## License
252-
253-
This project is licensed under the MIT License. See the LICENSE file for details.

0 commit comments

Comments
 (0)