[codex] add setApiUrl builder support

sdk/src/QonversionConfigBuilder.ts

@@ -20,6 +20,7 @@ export class QonversionConfigBuilder {
   private environment = Environment.Production;
   private logLevel = LogLevel.Info;
   private logTag = DEFAULT_LOG_TAG;
+  private apiUrl = API_URL;
 
   /**
    * Creates an instance of a builder
@@ -65,6 +66,35 @@ export class QonversionConfigBuilder {
     return this;
   };
 
+  /**
+   * Define the base API URL that the SDK will use for all network requests.
+   *
+   * This is primarily useful when routing the SDK through a trusted HTTPS proxy.
+   *
+   * @param apiUrl the desired HTTPS base API URL.
+   * @return builder instance for chain calls.
+   */
+  setApiUrl(apiUrl: string): QonversionConfigBuilder {
+    if (!apiUrl) {
+      throw new QonversionError(QonversionErrorCode.ConfigPreparation, "API URL is empty");
+    }
+
+    let normalizedUrl: URL;
+    try {
+      normalizedUrl = new URL(apiUrl);
+    } catch {
+      throw new QonversionError(QonversionErrorCode.ConfigPreparation, "API URL is invalid");
+    }
+
+    if (normalizedUrl.protocol !== 'https:') {
+      throw new QonversionError(QonversionErrorCode.ConfigPreparation, "API URL must use HTTPS");
+    }
+
+    this.apiUrl = normalizedUrl.toString().replace(/\/$/, '');
+
+    return this;
+  };
+
   /**
    * Generate {@link QonversionConfig} instance with all the provided configurations.
    *
@@ -89,7 +119,7 @@ export class QonversionConfigBuilder {
 
     const networkConfig: NetworkConfig = {
       canSendRequests: true,
-      apiUrl: API_URL,
+      apiUrl: this.apiUrl,
     };
 
     return {

sdk/src/__tests__/QonversionConfigBuilder.test.ts

@@ -58,6 +58,18 @@ test('setting log tag', () => {
   expect(builder["logTag"]).toBe(logTag);
 });
 
+test('setting api url', () => {
+  // given
+  const builder = new QonversionConfigBuilder('test');
+  const apiUrl = 'https://proxy.example.com';
+
+  // when
+  builder.setApiUrl(apiUrl);
+
+  // then
+  expect(builder["apiUrl"]).toBe(apiUrl);
+});
+
 test('successful build with full list of arguments', () => {
   // given
   const mockLogLevel = LogLevel.Warning;
@@ -132,6 +144,36 @@ test('successful build without full list of arguments', () => {
   expect(result).toStrictEqual(expResult);
 });
 
+test('successful build with custom api url', () => {
+  // given
+  const projectKey = "test key";
+  const apiUrl = 'https://proxy.example.com';
+
+  const builder = new QonversionConfigBuilder(projectKey);
+  builder.setApiUrl(apiUrl);
+
+  // when
+  const result = builder.build()
+
+  // then
+  expect(result.networkConfig.apiUrl).toBe(apiUrl);
+});
+
+test('normalizes custom api url by removing trailing slash', () => {
+  // given
+  const projectKey = "test key";
+  const apiUrl = 'https://proxy.example.com/';
+
+  const builder = new QonversionConfigBuilder(projectKey);
+  builder.setApiUrl(apiUrl);
+
+  // when
+  const result = builder.build()
+
+  // then
+  expect(result.networkConfig.apiUrl).toBe('https://proxy.example.com');
+});
+
 test('building with blank project key', () => {
   // given
   const builder = new QonversionConfigBuilder("");
@@ -140,3 +182,30 @@ test('building with blank project key', () => {
   // when and then
   expectQonversionError(QonversionErrorCode.ConfigPreparation, testingMethod);
 });
+
+test('building with blank api url throws', () => {
+  // given
+  const builder = new QonversionConfigBuilder("test");
+  const testingMethod = () => builder.setApiUrl("");
+
+  // when and then
+  expectQonversionError(QonversionErrorCode.ConfigPreparation, testingMethod);
+});
+
+test('building with invalid api url throws', () => {
+  // given
+  const builder = new QonversionConfigBuilder("test");
+  const testingMethod = () => builder.setApiUrl("not a url");
+
+  // when and then
+  expectQonversionError(QonversionErrorCode.ConfigPreparation, testingMethod);
+});
+
+test('building with non-https api url throws', () => {
+  // given
+  const builder = new QonversionConfigBuilder("test");
+  const testingMethod = () => builder.setApiUrl("http://proxy.example.com");
+
+  // when and then
+  expectQonversionError(QonversionErrorCode.ConfigPreparation, testingMethod);
+});