Add data model and interface for parse equity file capability (#127)

Author: rabcat

flux_sdk/equity/__init__.py

@@ -0,0 +1 @@
+python_sources()

flux_sdk/equity/capabilities/__init__.py

@@ -0,0 +1,68 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class Currency(BaseModel):
+    amount: float
+    currency_type: str
+
+
+class EquityVestingEvent(BaseModel):
+    """
+    vest_date: the date on which the vesting event happens
+    vest_quantity: the total quantity of the vesting event
+    vested_quantity: the quantity which is vested
+    vest_performance_condition: sometimes, a vesting event is tied to extra condition like employee performance,
+    i.e. it's not necessarily vested past the vest_date
+    """
+    vest_date: datetime
+    vest_quantity: float
+    vested_quantity: float
+    vest_performance_condition: bool
+
+
+class EquityGrant(BaseModel):
+    """
+    external_stakeholder_identifier: the identifier of the equity grant owner in the third party system
+    internal_stakeholder_identifier: the identifier of the equity grant owner within Rippling system, can be rwc id
+    grant_unique_identifier: a unique identifier for the grant, i.e. different for each grant
+    grant_name: the name of the grant
+    grant_date: the date when the grant is created
+    canceled_date: the date when the grant is canceled
+    grant_price: the price of the grant
+    expiration_date: the date when the grant is expired
+    exercised_quantity: exercised quantity of the grant
+    released_quantity: released quantity of the grant
+    canceled_quantity: canceled quantity of the grant
+    expired_quantity: expired quantity of the grant
+    exercisable_quantity: exercisable quantity of the grant
+    exercise_price: exercise price of the grant
+    outstanding_quantity: outstanding quantity of the grant, also considered as valid quantity
+    outstanding_vested_quantity: vested quantity within the outstanding quantity
+    outstanding_unvested_quantity: unvested quantity within the outstanding quantity
+    vesting_events: list of vesting events that belong to the grant
+    extra: fields that are specific to some third parties and might not be needed in every use case
+    """
+
+    external_stakeholder_identifier: str
+    internal_stakeholder_identifier: str | None = None
+    grant_unique_identifier: str
+    grant_name: str
+    grant_date: datetime
+    canceled_date: datetime | None = None
+    grant_price: Currency
+    expiration_date: datetime | None = None
+    grant_quantity: float
+    exercised_quantity: float = 0.0
+    released_quantity: float = 0.0
+    canceled_quantity: float = 0.0
+    expired_quantity: float = 0.0
+    exercisable_quantity: float = 0.0
+    exercise_price: Currency | None = None
+    outstanding_quantity: float
+    outstanding_vested_quantity: float
+    outstanding_unvested_quantity: float
+    vesting_events: list[EquityVestingEvent]
+    extras: dict[str, Any]

flux_sdk/equity/capabilities/update_equity_grant/BUILD

@@ -0,0 +1,21 @@
+from abc import ABC, abstractmethod
+from io import StringIO
+
+from flux_sdk.equity.capabilities.update_equity_grant.data_models import EquityGrant
+
+
+class UpdateEquityGrant(ABC):
+    """
+    Update equity grant data from third party cap table providers.
+
+    This class represents the "update_equity_grant" capability. The developer is supposed to implement
+    update_equity_grant method in their implementation. For further details regarding their
+    implementation details, check their documentation.
+    """
+    @staticmethod
+    @abstractmethod
+    def update_equity_grant(stream: StringIO) -> dict[str, EquityGrant]:
+        """
+        This method parses the equity data stream and returns a dictionary of equity grant unique identifier to equity
+        grant
+        """

flux_sdk/equity/capabilities/update_equity_grant/__init__.py

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "rippling-flux-sdk"
-version = "0.56"
+version = "0.57"
 description = "Defines the interfaces and data-models used by Rippling Flux Apps."
 authors = ["Rippling Apps <[email protected]>"]
 readme = "README.md"
@@ -10,6 +10,8 @@ packages = [{include="flux_sdk"}]
 python = "^3.10"
 "ruamel.yaml" = "0.17.10"
 click = ">=8.0,<9"
+pydantic = {version = "2.9.0", extras = ["email"] }
+pydantic-core = "*"  # tied to pydantic version
 
 [tool.poetry.group.dev.dependencies]
 pytest = "7.2.1"