fix!: update-error-handling-across-packages

Author: ryanbas21

.changeset/wellknown-only-config.md

@@ -0,0 +1,43 @@
+---
+'@forgerock/journey-client': major
+---
+
+BREAKING: Unify journey-client around wellknown-only configuration
+
+This release simplifies the configuration API by requiring the `wellknown` URL and automatically inferring `baseUrl` and `realmPath`.
+
+## Breaking Changes
+
+- **Removed `baseUrl` from `JourneyServerConfig`**: The `baseUrl` is now always inferred from the wellknown URL. If inference fails (non-AM server), an error is returned.
+- **Removed `hasWellknownConfig` export**: This type guard is no longer needed since all configs use wellknown.
+
+## Migration
+
+**Before:**
+```typescript
+journey({
+  config: {
+    serverConfig: { baseUrl: 'https://am.example.com/am/' },
+    realmPath: 'alpha',
+  },
+});
+```
+
+**After:**
+```typescript
+journey({
+  config: {
+    serverConfig: {
+      wellknown: 'https://am.example.com/am/oauth2/alpha/.well-known/openid-configuration',
+    },
+    // realmPath is now optional - inferred from wellknown issuer
+  },
+});
+```
+
+## Features
+
+- Automatic `baseUrl` inference from wellknown URL (extracts path before `/oauth2/`)
+- Automatic `realmPath` inference from wellknown issuer
+- Improved error messages for non-AM servers, guiding users to appropriate clients
+- Updated README with comprehensive API documentation

e2e/am-mock-api/src/app/routes.auth.js

@@ -668,6 +668,11 @@ export default function (app) {
     res.send(wellKnownForgeRock);
   });
 
+  // Standard AM wellknown endpoint path (used by journey-client wellknown discovery)
+  app.get('/am/oauth2/realms/root/.well-known/openid-configuration', (req, res) => {
+    res.send(wellKnownForgeRock);
+  });
+
   app.get('/as/.well-known/new-oidc-configuration', (req, res) => {
     res.send(newPiWellKnown);
   });

e2e/journey-app/main.ts

@@ -6,7 +6,7 @@
  */
 import './style.css';
 
-import { journey } from '@forgerock/journey-client';
+import { journey, isJourneyClient } from '@forgerock/journey-client';
 
 import type { RequestMiddleware } from '@forgerock/journey-client/types';
 
@@ -51,12 +51,23 @@ if (searchParams.get('middleware') === 'true') {
 }
 
 (async () => {
-  const journeyClient = await journey({ config: config, requestMiddleware });
-
   const errorEl = document.getElementById('error') as HTMLDivElement;
   const formEl = document.getElementById('form') as HTMLFormElement;
   const journeyEl = document.getElementById('journey') as HTMLDivElement;
 
+  const journeyClientResult = await journey({ config: config, requestMiddleware });
+  if (!isJourneyClient(journeyClientResult)) {
+    console.error('Failed to initialize journey client:', journeyClientResult.message);
+    errorEl.textContent = journeyClientResult.message ?? 'Unknown error';
+    return;
+  }
+  /**
+   * Re-assign to a new const after type narrowing.
+   * TypeScript's type narrowing doesn't persist into closures (event handlers, callbacks)
+   * because it can't prove the variable wasn't reassigned between the guard and closure execution.
+   * Creating a new const binding after the guard preserves the narrowed type for nested functions.
+   */
+  const journeyClient = journeyClientResult;
   let step = await journeyClient.start({ journey: journeyName });
 
   function renderComplete() {

e2e/journey-app/server-configs.ts

@@ -6,17 +6,27 @@
  */
 import type { JourneyClientConfig } from '@forgerock/journey-client/types';
 
+/**
+ * Server configurations for E2E tests.
+ *
+ * Both baseUrl and realmPath are automatically inferred from the wellknown URL:
+ * - baseUrl: extracted from the path before `/oauth2/`
+ * - realmPath: extracted from the issuer URL in the wellknown response
+ */
 export const serverConfigs: Record<string, JourneyClientConfig> = {
   basic: {
     serverConfig: {
-      baseUrl: 'http://localhost:9443/am',
+      wellknown: 'http://localhost:9443/am/oauth2/realms/root/.well-known/openid-configuration',
+      // baseUrl inferred: http://localhost:9443/am/
+      // realmPath inferred from issuer: 'root'
     },
-    realmPath: 'root',
   },
   tenant: {
     serverConfig: {
-      baseUrl: 'https://openam-sdks.forgeblocks.com/am',
+      wellknown:
+        'https://openam-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
+      // baseUrl inferred: https://openam-sdks.forgeblocks.com/am/
+      // realmPath inferred from issuer: 'alpha'
     },
-    realmPath: 'alpha',
   },
 };