Skip to content

Commit 698f24e

Browse files
vatsalparikhvatsalparikh
committed
docs(journey-client): fix FRDevice mapping, export PolicyParams, improve migration guide
1 parent 44f9be3 commit 698f24e

7 files changed

Lines changed: 105 additions & 11 deletions

File tree

‎.changeset/cool-kings-learn.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@forgerock/journey-client': patch
3+
---
4+
5+
patch @forgerock/journey-client: export PolicyParams from journey-client/types

‎MIGRATION.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,37 @@ if ('error' in result) {
150150

151151
---
152152

153+
## StepOptions → StartParam / NextOptions / ResumeOptions
154+
155+
For the full type-level mapping see [`interface_mapping.md` § Authentication Flow](./interface_mapping.md#3-authentication-flow). The three implementation pain points that aren't obvious from the type table:
156+
157+
**1. `tree` is no longer threaded through `next()`.**
158+
159+
The legacy pattern merged `initOptions` and `nextOptions` and passed the combined object to both `start()` and `next()`, carrying `tree` through every call. In the new SDK, `next()` does not accept a journey name — it only takes `{ query? }`. Remove any options merging/forwarding from your `next()` wrapper.
160+
161+
```typescript
162+
// Legacy — options object merged and threaded through every call
163+
const options = { ...initOptions, ...nextOptions };
164+
await FRAuth.next(prevStep, options); // tree still in options
165+
166+
// New — next() has no journey param; don't merge options through
167+
await journeyClient.next(prevStep, { query: nextOptions?.query });
168+
```
169+
170+
**2. A journey stack stored `StepOptions[]`; it now stores `StartParam[]`.**
171+
172+
If you maintain a stack for switching between trees, the stored type changes from `StepOptions` to `StartParam` and the deduplication key changes from `tree` to `journey`:
173+
174+
```typescript
175+
// Legacy
176+
if (options?.tree !== current[current.length - 1]?.tree) { ... }
177+
178+
// New
179+
if (options?.journey !== current[current.length - 1]?.journey) { ... }
180+
```
181+
182+
---
183+
153184
## Step Types
154185

155186
| Legacy | New | Notes |
@@ -160,6 +191,58 @@ if ('error' in result) {
160191

161192
All step methods (`getCallbackOfType`, `getDescription`, `getHeader`, `getStage`, `getSessionToken`, etc.) remain identical.
162193

194+
### Creating a JourneyStep for Tests and Stories
195+
196+
The legacy SDK created step objects by instantiating `new FRStep(payload)`, `new FRLoginSuccess(payload)`, or `new FRLoginFailure(payload)`. The new SDK creates these internally — there are no classes to instantiate. Because all three types are plain objects, replace every `new FR*` call with an object literal typed against the corresponding interface:
197+
198+
```typescript
199+
// Before
200+
import { FRStep, FRLoginSuccess, FRLoginFailure } from '@forgerock/javascript-sdk';
201+
const step = new FRStep(payload);
202+
const success = new FRLoginSuccess(payload);
203+
const failure = new FRLoginFailure(payload);
204+
205+
// After
206+
import type {
207+
JourneyStep,
208+
JourneyLoginSuccess,
209+
JourneyLoginFailure,
210+
} from '@forgerock/journey-client/types';
211+
import { StepType, createCallback } from '@forgerock/journey-client/types';
212+
213+
const mockStep: JourneyStep = {
214+
type: StepType.Step,
215+
payload: rawPayload,
216+
callbacks: rawPayload.callbacks?.map(createCallback) ?? [],
217+
getCallbackOfType: (type) => {
218+
throw new Error('not implemented');
219+
},
220+
getCallbacksOfType: (type) => [],
221+
setCallbackValue: () => {},
222+
getDescription: () => undefined,
223+
getHeader: () => undefined,
224+
getStage: () => undefined,
225+
};
226+
227+
const mockSuccess: JourneyLoginSuccess = {
228+
type: StepType.LoginSuccess,
229+
payload: rawPayload,
230+
getRealm: () => 'alpha',
231+
getSessionToken: () => 'abc123',
232+
getSuccessUrl: () => undefined,
233+
};
234+
235+
const mockFailure: JourneyLoginFailure = {
236+
type: StepType.LoginFailure,
237+
payload: rawPayload,
238+
getCode: () => 401,
239+
getDetail: () => undefined,
240+
getMessage: () => 'Login failure',
241+
getReason: () => undefined,
242+
getProcessedMessage: () => [],
243+
};
244+
```
245+
163246
---
164247

165248
## HTTP Client

‎interface_mapping.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ Flat lookup table for AI context injection. Every legacy symbol → new import i
105105
| `ErrorCode` | Removed — use `GenericError.type` instead |
106106
| `FRAuth` | `import { journey } from '@forgerock/journey-client'` — factory returns `JourneyClient` |
107107
| `FRCallback` | `import { BaseCallback } from '@forgerock/journey-client/types'` |
108-
| `FRDevice` | `import { deviceClient } from '@forgerock/device-client'` |
108+
| `FRDevice` | `import { Device } from '@forgerock/journey-client/device'` |
109109
| `FRLoginFailure` | `import type { JourneyLoginFailure } from '@forgerock/journey-client/types'` |
110110
| `FRLoginSuccess` | `import type { JourneyLoginSuccess } from '@forgerock/journey-client/types'` |
111111
| `FRPolicy` | `import { Policy } from '@forgerock/journey-client/policy'` |
@@ -178,7 +178,7 @@ The legacy SDK is a single package. The new SDK splits concerns across multiple
178178
| `import { deviceClient } from '@forgerock/javascript-sdk'` | `import { deviceClient } from '@forgerock/device-client'` | deviceClient |
179179
| `import { FRAuth } from '@forgerock/javascript-sdk'` | `import { journey } from '@forgerock/journey-client'` | FRAuth |
180180
| `import { FRCallback } from '@forgerock/javascript-sdk'` | `import { BaseCallback } from '@forgerock/journey-client/types'` | FRCallback |
181-
| `import { FRDevice } from '@forgerock/javascript-sdk'` | `import { deviceClient } from '@forgerock/device-client'` | FRDevice |
181+
| `import { FRDevice } from '@forgerock/javascript-sdk'` | `import { Device } from '@forgerock/journey-client/device'` | FRDevice |
182182
| `import type { FRLoginFailure } from '@forgerock/javascript-sdk'` | `import type { JourneyLoginFailure } from '@forgerock/journey-client/types'` | FRLoginFailure |
183183
| `import type { FRLoginSuccess } from '@forgerock/javascript-sdk'` | `import type { JourneyLoginSuccess } from '@forgerock/journey-client/types'` | FRLoginSuccess |
184184
| `import { FRPolicy } from '@forgerock/javascript-sdk'` | `import { Policy } from '@forgerock/journey-client/policy'` | FRPolicy |
@@ -955,10 +955,10 @@ if (type === WebAuthnStepType.Authentication) {
955955

956956
### FRDevice (Device Profile Collection)
957957

958-
| Legacy API | New API | Return Type Change | Behavioral Notes |
959-
| ---------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------- |
960-
| `import { FRDevice } from '@forgerock/javascript-sdk'` | Device profile functionality via `@forgerock/device-client` | — | Class-based → factory function |
961-
| `new FRDevice(config?).getProfile({ location, metadata })` | `deviceClient(config).profile.get(query)` | `DeviceProfileData` → `ProfileDevice[] \| { error }` | Returns error object instead of throwing |
958+
| Legacy API | New API | Return Type Change | Behavioral Notes |
959+
| ---------------------------------------------------------- | ----------------------------------------------------------- | ------------------ | ---------------------------------------------------------------- |
960+
| `import { FRDevice } from '@forgerock/javascript-sdk'` | `import { Device } from '@forgerock/journey-client/device'` | — | Class renamed `FRDevice` → `Device`. **Subpath import required** |
961+
| `new FRDevice(config?).getProfile({ location, metadata })` | `new Device(config?).getProfile({ location, metadata })` | Same | Same signature and return type (`DeviceProfileData`) |
962962

963963
### deviceClient (Device CRUD Operations)
964964

‎packages/journey-client/api-report/journey-client.api.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import { isValidWellknownUrl } from '@forgerock/sdk-utilities';
1919
import { LogLevel } from '@forgerock/sdk-logger';
2020
import { NameValue } from '@forgerock/sdk-types';
2121
import { PolicyKey } from '@forgerock/sdk-types';
22+
import { PolicyParams } from '@forgerock/sdk-types';
2223
import { PolicyRequirement } from '@forgerock/sdk-types';
2324
import { RequestMiddleware } from '@forgerock/sdk-request-middleware';
2425
import { Step } from '@forgerock/sdk-types';
@@ -338,6 +339,8 @@ export class PingOneProtectInitializeCallback extends BaseCallback {
338339

339340
export { PolicyKey }
340341

342+
export { PolicyParams }
343+
341344
export { PolicyRequirement }
342345

343346
// @public

‎packages/journey-client/api-report/journey-client.types.api.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import type { AsyncLegacyConfigOptions } from '@forgerock/sdk-types';
99
import { AuthResponse } from '@forgerock/sdk-types';
1010
import { Callback } from '@forgerock/sdk-types';
1111
import { CallbackType } from '@forgerock/sdk-types';
12+
import { callbackType } from '@forgerock/sdk-types';
1213
import { createWellknownError } from '@forgerock/sdk-utilities';
1314
import { CustomLogger } from '@forgerock/sdk-logger';
1415
import { FailedPolicyRequirement } from '@forgerock/sdk-types';
@@ -18,6 +19,7 @@ import { isValidWellknownUrl } from '@forgerock/sdk-utilities';
1819
import { LogLevel } from '@forgerock/sdk-logger';
1920
import { NameValue } from '@forgerock/sdk-types';
2021
import { PolicyKey } from '@forgerock/sdk-types';
22+
import { PolicyParams } from '@forgerock/sdk-types';
2123
import { PolicyRequirement } from '@forgerock/sdk-types';
2224
import { RequestMiddleware } from '@forgerock/sdk-request-middleware';
2325
import { Step } from '@forgerock/sdk-types';
@@ -61,6 +63,8 @@ export type CallbackFactory = (callback: Callback) => BaseCallback;
6163

6264
export { CallbackType }
6365

66+
export { callbackType }
67+
6468
// @public
6569
export class ChoiceCallback extends BaseCallback {
6670
constructor(payload: Callback);
@@ -325,6 +329,8 @@ export class PingOneProtectInitializeCallback extends BaseCallback {
325329

326330
export { PolicyKey }
327331

332+
export { PolicyParams }
333+
328334
export { PolicyRequirement }
329335

330336
// @public

‎packages/journey-client/src/index.ts‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,3 @@
77

88
export * from './lib/client.store.js';
99
export * from './types.js';
10-
11-
// Re-export types from internal packages that consumers need
12-
export { callbackType } from '@forgerock/sdk-types';

‎packages/journey-client/src/types.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,17 +12,17 @@ export type {
1212
Step,
1313
Callback,
1414
CallbackType,
15-
StepType,
1615
GenericError,
1716
PolicyRequirement,
1817
FailedPolicyRequirement,
1918
NameValue,
19+
PolicyParams,
2020
StepDetail,
2121
AuthResponse,
2222
FailureDetail,
2323
} from '@forgerock/sdk-types';
2424

25-
export { PolicyKey } from '@forgerock/sdk-types';
25+
export { callbackType, PolicyKey, StepType } from '@forgerock/sdk-types';
2626

2727
// Re-export local types
2828
export * from './lib/client.types.js';

0 commit comments

Comments
 (0)