feat(audience): add typed event schemas and IdentityType (SDK-147)

Public schema surface for the Audience SDK:

- IEvent interface: EventName + ToProperties contract that the
  singleton's Track(IEvent) overload consumes. Usable by custom
  IEvent implementations as well as the built-in typed events.
- Progression / Resource / Purchase / MilestoneReached: the four
  typed gameplay events with Required / Optional field hints and
  enum-to-wire mappers that throw on unknown casts.
- Purchase validates ISO 4217 three-letter uppercase currency codes
  via a hand-rolled IsIso4217 helper (no System.Text.RegularExpressions,
  keeps IL2CPP build small).
- MilestoneReached rejects null or empty Name.
- ProgressionStatus (Start/Complete/Fail) and ResourceFlow
  (Source/Sink) enums with matching ToWireString extensions.
- IdentityType enum for the eight backend-accepted provider names
  (Passport, Steam, Epic, Google, Apple, Discord, Email, Custom)
  plus its ToWireString mapper.

The event classes throw ArgumentException from ToProperties on
invalid payloads; the singleton's Track(IEvent) catches and drops
with a warning so a buggy call site cannot crash the game.

Author: ImmutableJeffrey

src/Packages/Audience/Runtime/Events/IEvent.cs

@@ -0,0 +1,11 @@
+using System.Collections.Generic;
+
+namespace Immutable.Audience
+{
+    // Typed event contract for ImmutableAudience.Track(IEvent).
+    public interface IEvent
+    {
+        string EventName { get; }
+        Dictionary<string, object> ToProperties();
+    }
+}

src/Packages/Audience/Runtime/Events/TypedEvents.cs

@@ -0,0 +1,175 @@
+using System;
+using System.Collections.Generic;
+
+namespace Immutable.Audience
+{
+    // Progression event state.
+    public enum ProgressionStatus
+    {
+        Start,
+        Complete,
+        Fail
+    }
+
+    internal static class ProgressionStatusExtensions
+    {
+        // Throws on unknown casts. Progression.ToProperties propagates, and
+        // Track(IEvent) catches + drops with a warning.
+        internal static string ToWireString(this ProgressionStatus status) => status switch
+        {
+            ProgressionStatus.Start => "start",
+            ProgressionStatus.Complete => "complete",
+            ProgressionStatus.Fail => "fail",
+            _ => throw new ArgumentOutOfRangeException(
+                nameof(status), status, "Unhandled ProgressionStatus"),
+        };
+    }
+
+    // Player progressing through a world / level / stage.
+    public class Progression : IEvent
+    {
+        // Required.
+        public ProgressionStatus Status { get; set; }
+        // Optional.
+        public string World { get; set; }
+        public string Level { get; set; }
+        public string Stage { get; set; }
+        public int? Score { get; set; }
+        public float? DurationSec { get; set; }
+
+        public string EventName => "progression";
+
+        public Dictionary<string, object> ToProperties()
+        {
+            var props = new Dictionary<string, object>
+            {
+                ["status"] = Status.ToWireString()
+            };
+
+            if (World != null) props["world"] = World;
+            if (Level != null) props["level"] = Level;
+            if (Stage != null) props["stage"] = Stage;
+            if (Score.HasValue) props["score"] = Score.Value;
+            if (DurationSec.HasValue) props["durationSec"] = DurationSec.Value;
+
+            return props;
+        }
+    }
+
+    // Resource flow direction.
+    public enum ResourceFlow
+    {
+        Source,
+        Sink
+    }
+
+    internal static class ResourceFlowExtensions
+    {
+        // Throws on unknown casts. Resource.ToProperties propagates, and
+        // Track(IEvent) catches + drops with a warning.
+        internal static string ToWireString(this ResourceFlow flow) => flow switch
+        {
+            ResourceFlow.Source => "source",
+            ResourceFlow.Sink => "sink",
+            _ => throw new ArgumentOutOfRangeException(
+                nameof(flow), flow, "Unhandled ResourceFlow"),
+        };
+    }
+
+    // In-game currency earned or spent.
+    public class Resource : IEvent
+    {
+        // Required.
+        public ResourceFlow Flow { get; set; }
+        public string Currency { get; set; }
+        public float Amount { get; set; }
+        // Optional.
+        public string ItemType { get; set; }
+        public string ItemId { get; set; }
+
+        public string EventName => "resource";
+
+        public Dictionary<string, object> ToProperties()
+        {
+            var props = new Dictionary<string, object>
+            {
+                ["flow"] = Flow.ToWireString(),
+                ["currency"] = Currency,
+                ["amount"] = Amount
+            };
+
+            if (ItemType != null) props["itemType"] = ItemType;
+            if (ItemId != null) props["itemId"] = ItemId;
+
+            return props;
+        }
+    }
+
+    // Real-money transaction.
+    public class Purchase : IEvent
+    {
+        // Required. ISO 4217 three-letter uppercase currency code.
+        public string Currency { get; set; }
+        // Required.
+        public decimal Value { get; set; }
+        // Optional.
+        public string ItemId { get; set; }
+        public string ItemName { get; set; }
+        public int? Quantity { get; set; }
+        public string TransactionId { get; set; }
+
+        public string EventName => "purchase";
+
+        // Hand-rolled to avoid pulling System.Text.RegularExpressions into the IL2CPP build.
+        private static bool IsIso4217(string s)
+        {
+            if (s == null || s.Length != 3) return false;
+            for (var i = 0; i < 3; i++)
+            {
+                var c = s[i];
+                if (c < 'A' || c > 'Z') return false;
+            }
+            return true;
+        }
+
+        public Dictionary<string, object> ToProperties()
+        {
+            if (!IsIso4217(Currency))
+                throw new ArgumentException(
+                    $"Purchase.Currency '{Currency}' must be a three-letter uppercase ISO 4217 code");
+
+            var props = new Dictionary<string, object>
+            {
+                ["currency"] = Currency,
+                ["value"] = Value
+            };
+
+            if (ItemId != null) props["itemId"] = ItemId;
+            if (ItemName != null) props["itemName"] = ItemName;
+            if (Quantity.HasValue) props["quantity"] = Quantity.Value;
+            if (TransactionId != null) props["transactionId"] = TransactionId;
+
+            return props;
+        }
+    }
+
+    // Named milestone or achievement.
+    public class MilestoneReached : IEvent
+    {
+        // Required.
+        public string Name { get; set; }
+
+        public string EventName => "milestone_reached";
+
+        public Dictionary<string, object> ToProperties()
+        {
+            if (string.IsNullOrEmpty(Name))
+                throw new ArgumentException("MilestoneReached.Name must not be null or empty");
+
+            return new Dictionary<string, object>
+            {
+                ["name"] = Name
+            };
+        }
+    }
+}

src/Packages/Audience/Runtime/IdentityType.cs

@@ -0,0 +1,34 @@
+namespace Immutable.Audience
+{
+    // Identity provider accepted by the Audience backend.
+    public enum IdentityType
+    {
+        Passport,
+        Steam,
+        Epic,
+        Google,
+        Apple,
+        Discord,
+        Email,
+        Custom,
+    }
+
+    internal static class IdentityTypeExtensions
+    {
+        // Returns null on unknown casts. The string overloads of Identify /
+        // Alias check for null/empty and drop + warn, so an out-of-range
+        // cast surfaces as a dropped event, not a corrupt wire payload.
+        internal static string ToWireString(this IdentityType type) => type switch
+        {
+            IdentityType.Passport => "passport",
+            IdentityType.Steam => "steam",
+            IdentityType.Epic => "epic",
+            IdentityType.Google => "google",
+            IdentityType.Apple => "apple",
+            IdentityType.Discord => "discord",
+            IdentityType.Email => "email",
+            IdentityType.Custom => "custom",
+            _ => null,
+        };
+    }
+}

src/Packages/Audience/Tests/Runtime/Events/TypedEventTests.cs

@@ -0,0 +1,132 @@
+using NUnit.Framework;
+
+namespace Immutable.Audience.Tests
+{
+    [TestFixture]
+    internal class TypedEventTests
+    {
+        [Test]
+        public void Progression_EventName_IsProgression()
+        {
+            Assert.AreEqual("progression", new Progression().EventName);
+        }
+
+        [Test]
+        public void Progression_Complete_ProducesCorrectProperties()
+        {
+            var evt = new Progression
+            {
+                Status = ProgressionStatus.Complete,
+                World = "tutorial",
+                Level = "1",
+                Score = 1500,
+                DurationSec = 120.5f
+            };
+
+            var props = evt.ToProperties();
+
+            Assert.AreEqual("complete", props["status"]);
+            Assert.AreEqual("tutorial", props["world"]);
+            Assert.AreEqual("1", props["level"]);
+            Assert.AreEqual(1500, props["score"]);
+            Assert.AreEqual(120.5f, props["durationSec"]);
+        }
+
+        [Test]
+        public void Progression_OptionalFieldsOmitted_WhenNull()
+        {
+            var props = new Progression { Status = ProgressionStatus.Start }.ToProperties();
+
+            Assert.IsTrue(props.ContainsKey("status"));
+            Assert.IsFalse(props.ContainsKey("world"));
+            Assert.IsFalse(props.ContainsKey("level"));
+            Assert.IsFalse(props.ContainsKey("stage"));
+            Assert.IsFalse(props.ContainsKey("score"));
+            Assert.IsFalse(props.ContainsKey("durationSec"));
+        }
+
+        [Test]
+        public void Resource_Source_ProducesCorrectProperties()
+        {
+            var evt = new Resource
+            {
+                Flow = ResourceFlow.Source,
+                Currency = "gold",
+                Amount = 100,
+                ItemType = "quest_reward",
+                ItemId = "main_quest_01"
+            };
+
+            var props = evt.ToProperties();
+
+            Assert.AreEqual("source", props["flow"]);
+            Assert.AreEqual("gold", props["currency"]);
+            Assert.AreEqual(100m, props["amount"]);
+            Assert.AreEqual("quest_reward", props["itemType"]);
+            Assert.AreEqual("main_quest_01", props["itemId"]);
+        }
+
+        [Test]
+        public void Resource_EventName_IsResource()
+        {
+            Assert.AreEqual("resource", new Resource().EventName);
+        }
+
+        [Test]
+        public void Purchase_ProducesCorrectProperties()
+        {
+            var evt = new Purchase
+            {
+                Currency = "USD",
+                Value = 9.99m,
+                ItemId = "gem_pack_01",
+                ItemName = "Starter Gem Pack",
+                Quantity = 1,
+                TransactionId = "txn_abc123"
+            };
+
+            var props = evt.ToProperties();
+
+            Assert.AreEqual("USD", props["currency"]);
+            Assert.AreEqual(9.99m, props["value"]);
+            Assert.AreEqual("gem_pack_01", props["itemId"]);
+            Assert.AreEqual("Starter Gem Pack", props["itemName"]);
+            Assert.AreEqual(1, props["quantity"]);
+            Assert.AreEqual("txn_abc123", props["transactionId"]);
+        }
+
+        [Test]
+        public void Purchase_OptionalFieldsOmitted_WhenNull()
+        {
+            var props = new Purchase { Currency = "EUR", Value = 5.00m }.ToProperties();
+
+            Assert.IsTrue(props.ContainsKey("currency"));
+            Assert.IsTrue(props.ContainsKey("value"));
+            Assert.IsFalse(props.ContainsKey("itemId"));
+            Assert.IsFalse(props.ContainsKey("itemName"));
+            Assert.IsFalse(props.ContainsKey("quantity"));
+            Assert.IsFalse(props.ContainsKey("transactionId"));
+        }
+
+        [Test]
+        public void Purchase_EventName_IsPurchase()
+        {
+            Assert.AreEqual("purchase", new Purchase().EventName);
+        }
+
+        [Test]
+        public void MilestoneReached_ProducesCorrectProperties()
+        {
+            var props = new MilestoneReached { Name = "first_boss_defeated" }.ToProperties();
+
+            Assert.AreEqual("first_boss_defeated", props["name"]);
+            Assert.AreEqual(1, props.Count);
+        }
+
+        [Test]
+        public void MilestoneReached_EventName_IsMilestoneReached()
+        {
+            Assert.AreEqual("milestone_reached", new MilestoneReached().EventName);
+        }
+    }
+}

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

@@ -0,0 +1,32 @@
+using NUnit.Framework;
+
+namespace Immutable.Audience.Tests
+{
+    [TestFixture]
+    internal class IdentityTypeTests
+    {
+        [TestCase(IdentityType.Passport, "passport")]
+        [TestCase(IdentityType.Steam, "steam")]
+        [TestCase(IdentityType.Epic, "epic")]
+        [TestCase(IdentityType.Google, "google")]
+        [TestCase(IdentityType.Apple, "apple")]
+        [TestCase(IdentityType.Discord, "discord")]
+        [TestCase(IdentityType.Email, "email")]
+        [TestCase(IdentityType.Custom, "custom")]
+        public void ToWireString_MapsEachEnumValueToLowercaseBackendString(IdentityType type, string expected)
+        {
+            Assert.AreEqual(expected, type.ToWireString());
+        }
+
+        [Test]
+        public void ToWireString_UnknownValue_ReturnsNull()
+        {
+            // Never-throw contract: an out-of-range cast should not surface an
+            // exception on the game thread. Callers drop the event via their
+            // null/empty check instead.
+            var invalid = (IdentityType)999;
+
+            Assert.IsNull(invalid.ToWireString());
+        }
+    }
+}