feat: add Builder pattern for DefaultClient with deprecated legacy constructor

Author: utkrishtsahu

EXAMPLES.md

@@ -3201,10 +3201,12 @@ The Auth0 class can be configured with a `NetworkingClient`, which will be used
 ### Timeout configuration
 
 ```kotlin
-val netClient = DefaultClient(
-    connectTimeout = 30,
-    readTimeout = 30
-)
+val netClient = DefaultClient.Builder()
+    .connectTimeout(30)
+    .readTimeout(30)
+    .writeTimeout(30)  
+    .callTimeout(120) 
+    .build()
 
 val account = Auth0.getInstance("{YOUR_CLIENT_ID}", "{YOUR_DOMAIN}")
 account.networkingClient = netClient
@@ -3214,43 +3216,78 @@ account.networkingClient = netClient
   <summary>Using Java</summary>
 
 ```java
-DefaultClient netClient = new DefaultClient(30, 30);
+DefaultClient netClient = new DefaultClient.Builder()
+    .connectTimeout(30)
+    .readTimeout(30)
+    .writeTimeout(30)
+    .callTimeout(120)
+    .build();
 Auth0 account = Auth0.getInstance("client id", "domain");
 account.setNetworkingClient(netClient);
 ```
 </details>
 
-### Logging configuration
+<details>
+  <summary>Legacy constructor (still supported)</summary>
 
 ```kotlin
 val netClient = DefaultClient(
-    enableLogging = true
+    connectTimeout = 30,
+    readTimeout = 30
 )
+```
+</details>
+
+### Logging configuration
+
+```kotlin
+val netClient = DefaultClient.Builder()
+    .enableLogging(true)
+    .build()
 
 val account = Auth0.getInstance("{YOUR_CLIENT_ID}", "{YOUR_DOMAIN}")
 account.networkingClient = netClient
 ```
 
+You can also customize the log level and provide a custom logger:
+
+```kotlin
+val netClient = DefaultClient.Builder()
+    .enableLogging(true)
+    .logLevel(HttpLoggingInterceptor.Level.HEADERS)  // NONE, BASIC, HEADERS, or BODY (default)
+    .logger(HttpLoggingInterceptor.Logger { message -> Log.d("Auth0Http", message) })
+    .build()
+```
+
 <details>
   <summary>Using Java</summary>
 
 ```java
-import java.util.HashMap;
-
-DefaultClient netClient = new DefaultClient(
-        10, 10, new HashMap<>() ,true
-);
+DefaultClient netClient = new DefaultClient.Builder()
+    .enableLogging(true)
+    .logLevel(HttpLoggingInterceptor.Level.HEADERS)
+    .build();
 Auth0 account = Auth0.getInstance("client id", "domain");
 account.setNetworkingClient(netClient);
 ```
 </details>
 
-### Set additional headers for all requests
+<details>
+  <summary>Legacy constructor (still supported)</summary>
 
 ```kotlin
 val netClient = DefaultClient(
-    defaultHeaders = mapOf("{HEADER-NAME}" to "{HEADER-VALUE}")
+    enableLogging = true
 )
+```
+</details>
+
+### Set additional headers for all requests
+
+```kotlin
+val netClient = DefaultClient.Builder()
+    .defaultHeaders(mapOf("{HEADER-NAME}" to "{HEADER-VALUE}"))
+    .build()
 
 val account = Auth0.getInstance("{YOUR_CLIENT_ID}", "{YOUR_DOMAIN}")
 account.networkingClient = netClient
@@ -3263,14 +3300,45 @@ account.networkingClient = netClient
 Map<String, String> defaultHeaders = new HashMap<>();
 defaultHeaders.put("{HEADER-NAME}", "{HEADER-VALUE}");
 
-DefaultClient netClient = new DefaultClient(
-        10,10 , defaultHeaders
-);
+DefaultClient netClient = new DefaultClient.Builder()
+    .defaultHeaders(defaultHeaders)
+    .build();
 Auth0 account = Auth0.getInstance("client id", "domain");
 account.setNetworkingClient(netClient);
 ```
 </details>
 
+<details>
+  <summary>Legacy constructor (still supported)</summary>
+
+```kotlin
+val netClient = DefaultClient(
+    defaultHeaders = mapOf("{HEADER-NAME}" to "{HEADER-VALUE}")
+)
+```
+</details>
+
+### Custom interceptors
+
+You can add custom OkHttp interceptors to the `DefaultClient` for use cases such as auth token injection, analytics, or certificate pinning:
+
+```kotlin
+val netClient = DefaultClient.Builder()
+    .addInterceptor(Interceptor { chain ->
+        val request = chain.request().newBuilder()
+            .addHeader("X-Request-Id", UUID.randomUUID().toString())
+            .build()
+        chain.proceed(request)
+    })
+    .addInterceptor(myAnalyticsInterceptor)
+    .build()
+
+val account = Auth0.getInstance("{YOUR_CLIENT_ID}", "{YOUR_DOMAIN}")
+account.networkingClient = netClient
+```
+
+Interceptors are invoked in the order they were added, after the built-in retry interceptor and before the logging interceptor.
+
 ### Advanced configuration
 
 For more advanced configuration of the networking client, you can provide a custom implementation of `NetworkingClient`. This may be useful when you wish to reuse your own networking client, configure a proxy, etc.

V4_MIGRATION_GUIDE.md

@@ -96,6 +96,37 @@ implementation 'com.google.code.gson:gson:2.8.9' // your preferred version
 
 > **Note:** Pinning or excluding is not recommended long-term, as the SDK has been tested and validated against Gson 2.11.0.
 
+### DefaultClient.Builder
+
+v4 introduces a `DefaultClient.Builder` for configuring the HTTP client. This replaces the constructor-based approach with a more flexible builder pattern that supports additional options such as write/call timeouts, custom interceptors, and custom loggers.
+
+**v3 (constructor-based — deprecated):**
+
+```kotlin
+// ⚠️ Deprecated: still compiles but shows a warning
+val client = DefaultClient(
+    connectTimeout = 30,
+    readTimeout = 30,
+    enableLogging = true
+)
+```
+
+**v4 (builder pattern — recommended):**
+
+```kotlin
+val client = DefaultClient.Builder()
+    .connectTimeout(30)
+    .readTimeout(30)
+    .writeTimeout(30)
+    .callTimeout(120)
+    .enableLogging(true)
+    .logLevel(HttpLoggingInterceptor.Level.HEADERS)
+    .addInterceptor(myCustomInterceptor)
+    .build()
+```
+
+The legacy constructor is deprecated but **not removed** — existing code will continue to compile and run. Your IDE will show a deprecation warning with a suggested `ReplaceWith` quick-fix to migrate to the Builder.
+
 ## Getting Help
 
 If you encounter issues during migration: