feat(audience): optional AudienceConfig.BaseUrl override

Addresses review feedback on #709 from @nattb8: match the Web/Pixel SDK
pattern of letting callers override the API base URL.

BaseUrl is null by default. A null override keeps the existing
key-prefix derivation — "pk_imapik-test-" keys resolve to Sandbox and
every other key resolves to Production — so there is no behaviour
change for studios that never set this field. Integrations that need a
different backend (for example the Immutable-internal Dev API at
https://api.dev.immutable.com) pass the URL directly; no public env
token is surfaced.

- AudienceConfig: new BaseUrl string? property.
- Constants: BaseUrl / MessagesUrl / ConsentUrl / DataUrl accept an
  optional baseUrlOverride; override wins when non-empty, falls back to
  key-prefix derivation when null or empty.
- HttpTransport: ctor accepts baseUrlOverride and threads it into
  MessagesUrl.
- ImmutableAudience.Init passes config.BaseUrl into HttpTransport;
  DeleteData and SyncConsentToBackend pass it into DataUrl / ConsentUrl.
- Tests: BaseUrl resolution cases (test key, non-test key, null key,
  override wins, empty-string override falls back) and an end-to-end
  HttpTransport test confirming the override wins over a sandbox-
  derived key.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ImmutableJeffrey

src/Packages/Audience/Runtime/AudienceConfig.cs

@@ -10,6 +10,11 @@ public class AudienceConfig
         // Studio API key. Required — Init throws if null.
         public string? PublishableKey { get; set; }
 
+        // Override the default API base URL. When null, keys starting with
+        // "pk_imapik-test-" resolve to Sandbox and all other keys resolve
+        // to Production. Set explicitly to target a different backend.
+        public string? BaseUrl { get; set; }
+
         // Initial consent level.
         public ConsentLevel Consent { get; set; } = ConsentLevel.None;
 

src/Packages/Audience/Runtime/Core/Constants.cs

@@ -26,14 +26,22 @@ internal static class Constants
 
         internal const string PublishableKeyHeader = "x-immutable-publishable-key";
 
-        internal static string MessagesUrl(string? publishableKey) => BaseUrl(publishableKey) + MessagesPath;
-        internal static string ConsentUrl(string? publishableKey) => BaseUrl(publishableKey) + ConsentPath;
-        internal static string DataUrl(string? publishableKey) => BaseUrl(publishableKey) + DataPath;
+        internal static string MessagesUrl(string? publishableKey, string? baseUrlOverride = null) =>
+            BaseUrl(publishableKey, baseUrlOverride) + MessagesPath;
+        internal static string ConsentUrl(string? publishableKey, string? baseUrlOverride = null) =>
+            BaseUrl(publishableKey, baseUrlOverride) + ConsentPath;
+        internal static string DataUrl(string? publishableKey, string? baseUrlOverride = null) =>
+            BaseUrl(publishableKey, baseUrlOverride) + DataPath;
 
-        internal static string BaseUrl(string? publishableKey) =>
-            publishableKey != null && publishableKey.StartsWith(TestKeyPrefix)
+        // Override wins when non-empty; otherwise test keys map to Sandbox
+        // and every other key maps to Production. Matches @imtbl/audience.
+        internal static string BaseUrl(string? publishableKey, string? baseUrlOverride = null)
+        {
+            if (!string.IsNullOrEmpty(baseUrlOverride)) return baseUrlOverride!;
+            return publishableKey != null && publishableKey.StartsWith(TestKeyPrefix)
                 ? SandboxBaseUrl
                 : ProductionBaseUrl;
+        }
     }
 
     // Message type values written to (and read back from) the "type" field.

src/Packages/Audience/Runtime/ImmutableAudience.cs

@@ -132,7 +132,7 @@ public static void Init(AudienceConfig config)
 
                 _store = new DiskStore(config.PersistentDataPath);
                 _queue = new EventQueue(_store, config.FlushIntervalSeconds, config.FlushSize);
-                _transport = new HttpTransport(_store, config.PublishableKey, config.OnError, config.HttpHandler);
+                _transport = new HttpTransport(_store, config.PublishableKey, config.BaseUrl, config.OnError, config.HttpHandler);
                 _controlClient = config.HttpHandler != null
                     ? new HttpClient(config.HttpHandler, disposeHandler: false)
                     : new HttpClient();
@@ -388,7 +388,7 @@ public static Task DeleteData(string? userId = null)
                 query = "anonymousId=" + Uri.EscapeDataString(anonymousId);
             }
 
-            var url = Constants.DataUrl(config.PublishableKey) + "?" + query;
+            var url = Constants.DataUrl(config.PublishableKey, config.BaseUrl) + "?" + query;
             var onError = config.OnError;
             var publishableKey = config.PublishableKey;
             var cancellationToken = _shutdownCancellationSource?.Token ?? CancellationToken.None;
@@ -550,7 +550,7 @@ private static void SyncConsentToBackend(AudienceConfig config, ConsentLevel lev
             var client = _controlClient;
             if (client == null) return;
 
-            var url = Constants.ConsentUrl(config.PublishableKey);
+            var url = Constants.ConsentUrl(config.PublishableKey, config.BaseUrl);
             var publishableKey = config.PublishableKey;
             var onError = config.OnError;
             var cancellationToken = _shutdownCancellationSource?.Token ?? CancellationToken.None;

src/Packages/Audience/Runtime/Transport/HttpTransport.cs

@@ -28,18 +28,20 @@ internal sealed class HttpTransport : IDisposable
 
         // store: source of event batches.
         // publishableKey: sent as x-immutable-publishable-key on every request.
+        // baseUrlOverride: explicit backend URL. Null = derive from publishableKey prefix.
         // onError: optional failure callback. Exceptions thrown inside it are caught.
         // handler / getUtcNow: test seams; null for production use.
         internal HttpTransport(
             DiskStore store,
             string publishableKey,
+            string? baseUrlOverride = null,
             Action<AudienceError>? onError = null,
             HttpMessageHandler? handler = null,
             Func<DateTime>? getUtcNow = null)
         {
             _store = store ?? throw new ArgumentNullException(nameof(store));
             _publishableKey = publishableKey ?? throw new ArgumentNullException(nameof(publishableKey));
-            _url = Constants.MessagesUrl(publishableKey);
+            _url = Constants.MessagesUrl(publishableKey, baseUrlOverride);
             _onError = onError;
             // disposeHandler: false so the consumer can reuse their handler
             // across Init/Shutdown cycles (matches _controlClient's policy).

src/Packages/Audience/Tests/Runtime/ConstantsTests.cs

@@ -6,6 +6,54 @@ namespace Immutable.Audience.Tests
     [TestFixture]
     internal class ConstantsTests
     {
+        // -----------------------------------------------------------------
+        // BaseUrl resolution
+        // -----------------------------------------------------------------
+
+        [Test]
+        public void BaseUrl_TestKey_ResolvesToSandbox()
+        {
+            Assert.AreEqual(Constants.SandboxBaseUrl,
+                Constants.BaseUrl("pk_imapik-test-abc"));
+        }
+
+        [Test]
+        public void BaseUrl_NonTestKey_ResolvesToProduction()
+        {
+            Assert.AreEqual(Constants.ProductionBaseUrl,
+                Constants.BaseUrl("pk_imapik-prod-abc"));
+        }
+
+        [Test]
+        public void BaseUrl_NullKey_ResolvesToProduction()
+        {
+            Assert.AreEqual(Constants.ProductionBaseUrl,
+                Constants.BaseUrl(null));
+        }
+
+        [Test]
+        public void BaseUrl_Override_WinsOverKeyPrefix()
+        {
+            // Override wins even for a test-prefixed key that would
+            // otherwise derive to Sandbox.
+            const string custom = "https://api.dev.immutable.com";
+            Assert.AreEqual(custom,
+                Constants.BaseUrl("pk_imapik-test-abc", custom));
+        }
+
+        [Test]
+        public void BaseUrl_EmptyOverride_FallsBackToKeyDerivation()
+        {
+            // Empty-string override is treated as "no override" so the
+            // key-prefix fallback still kicks in.
+            Assert.AreEqual(Constants.SandboxBaseUrl,
+                Constants.BaseUrl("pk_imapik-test-abc", ""));
+        }
+
+        // -----------------------------------------------------------------
+        // Library version
+        // -----------------------------------------------------------------
+
         [Test]
         public void LibraryVersion_MatchesPackageJson()
         {

src/Packages/Audience/Tests/Runtime/Transport/HttpTransportTests.cs

@@ -152,6 +152,25 @@ public async Task SendBatchAsync_200_UsesCorrectUrlForProdKey()
             StringAssert.StartsWith(Constants.ProductionBaseUrl, captured.RequestUri.ToString());
         }
 
+        [Test]
+        public async Task SendBatchAsync_BaseUrlOverride_WinsOverKeyPrefix()
+        {
+            _store.Write("{\"type\":\"track\"}");
+
+            HttpRequestMessage captured = null;
+            var handler = new MockHandler(HttpStatusCode.OK, "{\"accepted\":1,\"rejected\":0}",
+                onRequest: req => captured = req);
+            const string custom = "https://api.dev.immutable.com";
+            // Test-prefixed key would resolve to Sandbox on its own; the
+            // explicit override must win.
+            using var transport = new HttpTransport(_store, "pk_imapik-test-key1",
+                baseUrlOverride: custom, handler: handler);
+
+            await transport.SendBatchAsync();
+
+            StringAssert.StartsWith(custom, captured.RequestUri.ToString());
+        }
+
         [Test]
         public async Task SendBatchAsync_EmptyQueue_ReturnsFalse()
         {