@qlover/fe-corekit 3.0.0 → 3.1.0

package/dist/index.d.ts

@@ -7628,11 +7628,23 @@ declare function isRequestAdapterResponse(value: unknown): value is RequestAdapt
  * - URL normalization: Leverages native URL API for consistent path resolution
  * - Extensible design: Protected methods allow subclass customization
  *
+ * Important behaviors:
+ * - Path preservation: When using relative paths with base URLs that contain path segments,
+ *   the relative path is appended to the base URL's path instead of replacing it
+ * - Strict vs Non-strict mode: In strict mode, invalid base URLs cause errors;
+ *   in non-strict mode, they are handled gracefully
+ * - Authentication info: Preserves authentication credentials in base URLs (e.g., https://user:pass@domain.com/)
+ * - Hash fragments: Maintains hash fragments from both base URLs and relative paths
+ * - Query parameters: Combines query parameters from base URL and config, with new parameters taking precedence
+ *
  * Design considerations:
  * - Uses temporary domain (`http://temp`) for relative URL processing to leverage URL API
  * - Supports strict mode for stricter baseURL validation
  * - Returns path-only strings for relative URLs without valid baseURL
  *
+ * Configuration options:
+ * - strict: Enables strict mode for stricter validation of base URLs (default: false)
+ *
  * `@since` `3.0.0`
  *
  * @example Basic usage with absolute baseURL
@@ -7664,6 +7676,17 @@ declare function isRequestAdapterResponse(value: unknown): value is RequestAdapt
  *   baseURL: 'invalid-url' // Will throw error in strict mode
  * });
  * ```
+ *
+ * @example Preserving path segments in baseURL
+ * ```typescript
+ * const urlBuilder = new SimpleUrlBuilder();
+ * const url = urlBuilder.buildUrl({
+ *   url: '/api/token.json',
+ *   baseURL: 'https://brus-dev.api.brain.ai/v1.0/invoke/brain-user-system/method'
+ * });
+ * // Returns: 'https://brus-dev.api.brain.ai/v1.0/invoke/brain-user-system/method/api/token.json'
+ * // ✅ Correctly preserves the baseURL's path segment: '/v1.0/invoke/brain-user-system/method'
+ * ```
  */
 declare class SimpleUrlBuilder implements UrlBuilderInterface {
     /**
@@ -7773,6 +7796,17 @@ declare class SimpleUrlBuilder implements UrlBuilderInterface {
         urlObject: URL;
         shouldReturnPathOnly: boolean;
     };
+    /**
+     * Joins relative URL path to a base URL that has path segments
+     *
+     * This method addresses the issue where using new URL('/path', 'https://domain/base/path')
+     * would replace the entire path of the base URL instead of appending to it.
+     *
+     * @param relativePath - The relative path to append
+     * @param baseURL - The base URL to append to
+     * @returns URL object with properly joined paths
+     */
+    private joinPathsToBaseURL;
     /**
      * Builds complete URL from request configuration
      *
@@ -7786,6 +7820,11 @@ declare class SimpleUrlBuilder implements UrlBuilderInterface {
      * - `null` and `undefined` parameter values are filtered out
      * - Hash fragments are preserved in the final URL
      *
+     * **Bug Fix Note**: This implementation correctly handles baseURLs that contain
+     * path segments. Previous versions incorrectly lost the path portion when using
+     * `new URL(relativePath, baseURLWithPath)`. Now the relative path is properly
+     * appended to the base URL's path instead of replacing it.
+     *
      * @override
      * @param config - Request configuration containing URL components
      * @param {string} [config.url=''] - The URL path (absolute or relative)
@@ -7804,13 +7843,15 @@ declare class SimpleUrlBuilder implements UrlBuilderInterface {
      * // Returns: 'https://api.example.com/users?role=admin&page=1'
      * ```
      *
-     * @example Relative URL without baseURL
+     * @example Complex baseURL with path segments (Bug Fix Example)
      * ```typescript
      * const url = urlBuilder.buildUrl({
-     *   url: '/api/users',
-     *   params: { status: 'active' }
+     *   url: '/api/token.json',
+     *   baseURL: 'https://brus-dev.api.brain.ai/v1.0/invoke/brain-user-system/method',
+     *   params: { grant_type: 'authorization_code' }
      * });
-     * // Returns: '/api/users?status=active'
+     * // Returns: 'https://brus-dev.api.brain.ai/v1.0/invoke/brain-user-system/method/api/token.json?grant_type=authorization_code'
+     * // ✅ Correctly preserves the baseURL's path segment: '/v1.0/invoke/brain-user-system/method'
      * ```
      *
      * @example Absolute URL ignores baseURL