feat(javascript): add a isRecognizedBaseUrlPattern util

Author: brionmario

packages/javascript/src/index.ts

@@ -135,6 +135,7 @@ export {default as processUsername} from './utils/processUsername';
 export {default as deepMerge} from './utils/deepMerge';
 export {default as deriveOrganizationHandleFromBaseUrl} from './utils/deriveOrganizationHandleFromBaseUrl';
 export {default as extractUserClaimsFromIdToken} from './utils/extractUserClaimsFromIdToken';
+export {default as isRecognizedBaseUrlPattern} from './utils/isRecognizedBaseUrlPattern';
 export {default as extractPkceStorageKeyFromState} from './utils/extractPkceStorageKeyFromState';
 export {default as flattenUserSchema} from './utils/flattenUserSchema';
 export {default as generateUserProfile} from './utils/generateUserProfile';

packages/javascript/src/utils/__tests__/isRecognizedBaseUrlPattern.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) 2025, WSO2 LLC. (https://www.wso2.com).
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import isRecognizedBaseUrlPattern from '../isRecognizedBaseUrlPattern';
+import AsgardeoRuntimeError from '../../errors/AsgardeoRuntimeError';
+
+vi.mock('../logger', () => ({default: {warn: vi.fn()}}));
+
+describe('isRecognizedBaseUrlPattern', () => {
+  it('returns true for recognized Asgardeo base URL pattern', () => {
+    expect(isRecognizedBaseUrlPattern('https://dev.asgardeo.io/t/dxlab')).toBe(true);
+    expect(isRecognizedBaseUrlPattern('https://example.com/t/org')).toBe(true);
+    expect(isRecognizedBaseUrlPattern('https://foo.com/t/bar/')).toBe(true);
+    expect(isRecognizedBaseUrlPattern('https://foo.com/t/bar/extra')).toBe(true);
+  });
+
+  it('returns false for unrecognized base URL pattern', () => {
+    expect(isRecognizedBaseUrlPattern('https://dev.asgardeo.io/tenant/dxlab')).toBe(false);
+    expect(isRecognizedBaseUrlPattern('https://dev.asgardeo.io/')).toBe(false);
+    expect(isRecognizedBaseUrlPattern('https://dev.asgardeo.io/t')).toBe(false);
+    expect(isRecognizedBaseUrlPattern('https://dev.asgardeo.io/other/path')).toBe(false);
+  });
+
+  it('throws AsgardeoRuntimeError if baseUrl is undefined', () => {
+    expect(() => isRecognizedBaseUrlPattern(undefined)).toThrow(AsgardeoRuntimeError);
+
+    try {
+      isRecognizedBaseUrlPattern(undefined);
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(AsgardeoRuntimeError);
+      expect(e.message).toMatch(/Base URL is required/);
+    }
+  });
+
+  it('throws AsgardeoRuntimeError for invalid URL format', () => {
+    expect(() => isRecognizedBaseUrlPattern('not-a-valid-url')).toThrow(AsgardeoRuntimeError);
+
+    try {
+      isRecognizedBaseUrlPattern('not-a-valid-url');
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(AsgardeoRuntimeError);
+      expect(e.message).toMatch(/Invalid base URL format/);
+    }
+  });
+});

packages/javascript/src/utils/isRecognizedBaseUrlPattern.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) 2025, WSO2 LLC. (https://www.wso2.com). All Rights Reserved.
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import AsgardeoRuntimeError from "../errors/AsgardeoRuntimeError";
+import logger from "./logger";
+
+/**
+ * Utility to determine if sensible Asgardeo fallbacks can be used based on the given base URL.
+ *
+ * This checks if the URL follows the standard Asgardeo pattern: /t/{orgHandle}
+ * Returns true if sensible fallbacks (like deriving organization handle, tenant, etc.) can be used, false otherwise.
+ *
+ * @param baseUrl - The base URL of the Asgardeo identity server (string or undefined)
+ * @returns boolean - true if sensible fallbacks can be used, false otherwise
+ *
+ * @example
+ * isRecognizedBaseUrlPattern('https://dev.asgardeo.io/t/dxlab'); // true
+ * isRecognizedBaseUrlPattern('https://custom.example.com/auth'); // false
+ */
+const isRecognizedBaseUrlPattern = (baseUrl: string | undefined): boolean => {
+ if (!baseUrl) {
+    throw new AsgardeoRuntimeError(
+      'Base URL is required to derive if the `baseUrl` is recognized.',
+      'isRecognizedBaseUrlPattern-ValidationError-001',
+      'javascript',
+      'A valid base URL must be provided to derive if the `baseUrl` is recognized to use the sensible fallbacks.',
+    );
+  }
+
+  let parsedUrl: URL;
+
+  try {
+    parsedUrl = new URL(baseUrl);
+  } catch (error) {
+    throw new AsgardeoRuntimeError(
+      `Invalid base URL format: ${baseUrl}`,
+      'isRecognizedBaseUrlPattern-ValidationError-002',
+      'javascript',
+      'The provided base URL does not conform to valid URL syntax.',
+    );
+  }
+
+  // Extract the organization handle from the path pattern: /t/{orgHandle}
+  const pathSegments = parsedUrl.pathname?.split('/')?.filter(segment => segment?.length > 0);
+
+  if (pathSegments.length < 2 || pathSegments[0] !== 't') {
+    logger.warn('[isRecognizedBaseUrlPattern] The provided base URL does not follow the expected URL pattern (/t/{orgHandle}).');
+
+    return false;
+  }
+
+  return true;
+};
+
+export default isRecognizedBaseUrlPattern;