feat: new enterprise transaction data/signals

Makefile

@@ -75,6 +75,9 @@ test-all: quality ## run tests on every supported Python/Django combination
 
 validate: quality test ## run tests and quality checks
 
+isort:  ## fix improperly sorted imports
+	isort test_utils openedx_events manage.py setup.py
+
 selfcheck: ## check that the Makefile is well-formed
 	@echo "The Makefile is well-formed."
 

openedx_events/enterprise/data.py

@@ -4,8 +4,11 @@
 These attributes follow the form of attr objects specified in OEP-49 data
 pattern.
 """
+from datetime import datetime
+from uuid import UUID
 
 import attr
+from opaque_keys.edx.keys import CourseKey
 
 
 @attr.s(frozen=True)
@@ -22,3 +25,62 @@ class SubsidyRedemption:
     subsidy_identifier = attr.ib(type=str)
     content_key = attr.ib(type=str)
     lms_user_id = attr.ib(type=int)
+
+
+@attr.s(frozen=True)
+class LedgerTransactionReversal:
+    """
+    Attributes of an ``openedx_ledger.Reversal`` record.
+
+    Arguments:
+        uuid (str): Primary identifier of the record.
+        created (datetime): When the record was created.
+        modified (datetime): When the record was last modified.
+        idempotency_key (str): Client-generated unique value to achieve idempotency of operations.
+        quantity (int): How many units of value this reversal represents (e.g. USD cents).
+        state (str): Current lifecyle state of the record, one of (created, pending, committed, failed).
+    """
+
+    uuid = attr.ib(type=UUID)
+    created = attr.ib(type=datetime)
+    modified = attr.ib(type=datetime)
+    idempotency_key = attr.ib(type=str)
+    quantity = attr.ib(type=int)
+    state = attr.ib(type=str)
+
+
+@attr.s(frozen=True)
+class LedgerTransaction:
+    """
+    Attributes of an ``openedx_ledger.Transaction`` record.
+
+    Arguments:
+        uuid (UUID): Primary identifier of the Transaction.
+        created (datetime): When the record was created.
+        modified (datetime): When the record was last modified.
+        idempotency_key (str): Client-generated unique value to achieve idempotency of operations.
+        quantity (int): How many units of value this transaction represents (e.g. USD cents).
+        state (str): Current lifecyle state of the record, one of (created, pending, committed, failed).
+        ledger_uuid (UUID): The primary identifier of this Transaction's ledger object.
+        subsidy_access_policy_uuid (UUID): The primary identifier of the subsidy access policy for this transaction.
+        lms_user_id (int): The LMS user id of the user associated with this transaction.
+        content_key (CourseKey): The course (run) key associated with this transaction.
+        parent_content_key (str): The parent (just course, not run) key for the course key.
+        fulfillment_identifier (str): The identifier of the subsidized enrollment record for a learner,
+          generated durning enrollment.
+        reversal (LedgerTransactionReversal): Any reversal associated with this transaction.
+    """
+
+    uuid = attr.ib(type=UUID)
+    created = attr.ib(type=datetime)
+    modified = attr.ib(type=datetime)
+    idempotency_key = attr.ib(type=str)
+    quantity = attr.ib(type=int)
+    state = attr.ib(type=str)
+    ledger_uuid = attr.ib(type=UUID)
+    subsidy_access_policy_uuid = attr.ib(type=UUID)
+    lms_user_id = attr.ib(type=int)
+    content_key = attr.ib(type=CourseKey)
+    parent_content_key = attr.ib(type=str)
+    fulfillment_identifier = attr.ib(type=str)
+    reversal = attr.ib(type=LedgerTransactionReversal)

openedx_events/enterprise/signals.py

@@ -8,12 +8,12 @@
 docs/decisions/0003-events-payload.rst
 """
 
-from openedx_events.enterprise.data import SubsidyRedemption
+from openedx_events.enterprise.data import LedgerTransaction, SubsidyRedemption
 from openedx_events.tooling import OpenEdxPublicSignal
 
 # .. event_type: org.openedx.enterprise.subsidy.redeemed.v1
 # .. event_name: SUBSIDY_REDEEMED
-# .. event_description: emitted when an enterprise subsidy is utilized.
+# .. event_description: (deprecated) emitted when an enterprise subsidy is utilized.
 # .. event_data: SubsidyRedemption
 SUBSIDY_REDEEMED = OpenEdxPublicSignal(
     event_type="org.openedx.enterprise.subsidy.redeemed.v1",
@@ -24,11 +24,59 @@
 
 # .. event_type: org.openedx.enterprise.subsidy.redemption-reversed.v1
 # .. event_name: SUBSIDY_REDEMPTION_REVERSED
-# .. event_description: emitted when an enterprise subsidy is reversed.
+# .. event_description: (deprecated) emitted when an enterprise subsidy is reversed.
 # .. event_data: SubsidyRedemption
 SUBSIDY_REDEMPTION_REVERSED = OpenEdxPublicSignal(
     event_type="org.openedx.enterprise.subsidy.redemption-reversed.v1",
     data={
         "redemption": SubsidyRedemption,
     }
 )
+
+
+# .. event_type: org.openedx.enterprise_subsidies.ledger_transaction.created.v1
+# .. event_name: LEDGER_TRANSACTION_CREATED
+# .. event_description: emitted when an enterprise ledger transaction is created.
+# .. event_data: LedgerTransaction
+LEDGER_TRANSACTION_CREATED = OpenEdxPublicSignal(
+    event_type="org.openedx.enterprise_subsidies.ledger_transaction.created.v1",
+    data={
+        "ledger_transaction": LedgerTransaction,
+    }
+)
+
+
+# .. event_type: org.openedx.enterprise_subsidies.ledger_transaction.committed.v1
+# .. event_name: LEDGER_TRANSACTION_COMMITTED
+# .. event_description: emitted when an enterprise ledger transaction is committed.
+# .. event_data: LedgerTransaction
+LEDGER_TRANSACTION_COMMITTED = OpenEdxPublicSignal(
+    event_type="org.openedx.enterprise_subsidies.ledger_transaction.committed.v1",
+    data={
+        "ledger_transaction": LedgerTransaction,
+    }
+)
+
+
+# .. event_type: org.openedx.enterprise_subsidies.ledger_transaction.failed.v1
+# .. event_name: LEDGER_TRANSACTION_FAILED
+# .. event_description: emitted when an enterprise ledger transaction fails.
+# .. event_data: LedgerTransaction
+LEDGER_TRANSACTION_FAILED = OpenEdxPublicSignal(
+    event_type="org.openedx.enterprise_subsidies.ledger_transaction.failed.v1",
+    data={
+        "ledger_transaction": LedgerTransaction,
+    }
+)
+
+
+# .. event_type: org.openedx.enterprise_subsidies.ledger_transaction.reversed.v1
+# .. event_name: LEDGER_TRANSACTION_REVERSED
+# .. event_description: emitted when an enterprise ledger transaction is reversed.
+# .. event_data: LedgerTransaction
+LEDGER_TRANSACTION_REVERSED = OpenEdxPublicSignal(
+    event_type="org.openedx.enterprise_subsidies.ledger_transaction.reversed.v1",
+    data={
+        "ledger_transaction": LedgerTransaction,
+    }
+)

openedx_events/event_bus/avro/custom_serializers.py

@@ -4,6 +4,7 @@
 """
 from abc import ABC, abstractmethod
 from datetime import datetime
+from uuid import UUID
 
 from ccx_keys.locator import CCXLocator
 from opaque_keys.edx.keys import CourseKey, UsageKey
@@ -149,11 +150,33 @@ def deserialize(data: str):
         return LibraryUsageLocatorV2.from_string(data)
 
 
+class UuidAvroSerializer(BaseCustomTypeAvroSerializer):
+    """
+    CustomTypeAvroSerializer for the UUID class.
+
+    https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/avro-format.md#21-type-system-mapping
+    """
+
+    cls = UUID
+    field_type = PYTHON_TYPE_TO_AVRO_MAPPING[str]
+
+    @staticmethod
+    def serialize(obj) -> str:
+        """Serialize obj into string."""
+        return str(obj)
+
+    @staticmethod
+    def deserialize(data: str):
+        """Deserialize string into obj."""
+        return UUID(data)
+
+
 DEFAULT_CUSTOM_SERIALIZERS = [
     CourseKeyAvroSerializer,
     CcxCourseLocatorAvroSerializer,
     DatetimeAvroSerializer,
     LibraryLocatorV2AvroSerializer,
     LibraryUsageLocatorV2AvroSerializer,
     UsageKeyAvroSerializer,
+    UuidAvroSerializer,
 ]

openedx_events/event_bus/avro/tests/schemas/org+openedx+enterprise_subsidies+ledger_transaction+committed+v1_schema.avsc

@@ -0,0 +1,98 @@
+{
+  "name": "CloudEvent",
+  "type": "record",
+  "doc": "Avro Event Format for CloudEvents created with openedx_events/schema",
+  "fields": [
+    {
+      "name": "ledger_transaction",
+      "type": {
+        "name": "LedgerTransaction",
+        "type": "record",
+        "fields": [
+          {
+            "name": "uuid",
+            "type": "string"
+          },
+          {
+            "name": "created",
+            "type": "string"
+          },
+          {
+            "name": "modified",
+            "type": "string"
+          },
+          {
+            "name": "idempotency_key",
+            "type": "string"
+          },
+          {
+            "name": "quantity",
+            "type": "long"
+          },
+          {
+            "name": "state",
+            "type": "string"
+          },
+          {
+            "name": "ledger_uuid",
+            "type": "string"
+          },
+          {
+            "name": "subsidy_access_policy_uuid",
+            "type": "string"
+          },
+          {
+            "name": "lms_user_id",
+            "type": "long"
+          },
+          {
+            "name": "content_key",
+            "type": "string"
+          },
+          {
+            "name": "parent_content_key",
+            "type": "string"
+          },
+          {
+            "name": "fulfillment_identifier",
+            "type": "string"
+          },
+          {
+            "name": "reversal",
+            "type": {
+              "name": "LedgerTransactionReversal",
+              "type": "record",
+              "fields": [
+                {
+                  "name": "uuid",
+                  "type": "string"
+                },
+                {
+                  "name": "created",
+                  "type": "string"
+                },
+                {
+                  "name": "modified",
+                  "type": "string"
+                },
+                {
+                  "name": "idempotency_key",
+                  "type": "string"
+                },
+                {
+                  "name": "quantity",
+                  "type": "long"
+                },
+                {
+                  "name": "state",
+                  "type": "string"
+                }
+              ]
+            }
+          }
+        ]
+      }
+    }
+  ],
+  "namespace": "org.openedx.enterprise_subsidies.ledger_transaction.committed.v1"
+}