refactor: update customer property models to use new enums for property and relation types

Author: akhil-vamshi-konam

plane/models/customers.py

@@ -2,7 +2,10 @@
 
 from pydantic import BaseModel, ConfigDict, Field, RootModel, field_serializer, model_validator
 
-from .enums import PropertyType, RelationType
+from .enums import CustomerPropertyType, CustomerRelationType
+
+from .enums import PropertyType as PropertyType
+from .enums import RelationType as RelationType
 from .pagination import PaginatedResponse
 from .work_item_property_configurations import (
     DateAttributeSettings,
@@ -161,8 +164,8 @@ class CustomerProperty(BaseModel):
     description: str | None = None
     logo_props: Any | None = None
     sort_order: float | None = None
-    property_type: PropertyType
-    relation_type: RelationType | None = None
+    property_type: CustomerPropertyType
+    relation_type: CustomerRelationType | None = None
     is_required: bool | None = None
     default_value: list[str] | None = None
     settings: PropertySettings | dict = None
@@ -177,11 +180,11 @@ class CustomerProperty(BaseModel):
     options: list[CustomerPropertyOption] | None = None
 
     @field_serializer("property_type")
-    def serialize_property_type(self, value: PropertyType) -> str | None:
+    def serialize_property_type(self, value: CustomerPropertyType) -> str | None:
         return value.value if value else None
 
     @field_serializer("relation_type")
-    def serialize_relation_type(self, value: RelationType) -> str | None:
+    def serialize_relation_type(self, value: CustomerRelationType) -> str | None:
         return value.value if value else None
 
 
@@ -195,8 +198,8 @@ class CreateCustomerProperty(BaseModel):
     description: str | None = None
     logo_props: Any | None = None
     sort_order: float | None = None
-    property_type: PropertyType
-    relation_type: RelationType | None = None
+    property_type: CustomerPropertyType
+    relation_type: CustomerRelationType | None = None
     is_required: bool | None = None
     default_value: list[str] | None = None
     settings: PropertySettings = None
@@ -208,11 +211,11 @@ class CreateCustomerProperty(BaseModel):
     options: list[CreateCustomerPropertyOption] | None = None
 
     @field_serializer("property_type")
-    def serialize_property_type(self, value: PropertyType) -> str | None:
+    def serialize_property_type(self, value: CustomerPropertyType) -> str | None:
         return value.value if value else None
 
     @field_serializer("relation_type")
-    def serialize_relation_type(self, value: RelationType) -> str | None:
+    def serialize_relation_type(self, value: CustomerRelationType) -> str | None:
         return value.value if value else None
 
     @model_validator(mode="after")
@@ -223,7 +226,7 @@ def validate_settings_and_relation_type(self) -> "CreateCustomerProperty":
         relation_type = self.relation_type
 
         # TEXT properties require TextAttributeSettings
-        if prop_type == PropertyType.TEXT:
+        if prop_type == CustomerPropertyType.TEXT:
             if settings is None:
                 raise ValueError(
                     "settings with TextAttributeSettings is required for TEXT properties"
@@ -232,7 +235,7 @@ def validate_settings_and_relation_type(self) -> "CreateCustomerProperty":
                 raise ValueError("settings must be TextAttributeSettings for TEXT properties")
 
         # DATETIME properties require DateAttributeSettings
-        if prop_type == PropertyType.DATETIME:
+        if prop_type == CustomerPropertyType.DATETIME:
             if settings is None:
                 raise ValueError(
                     "settings with DateAttributeSettings is required for DATETIME properties"
@@ -241,7 +244,7 @@ def validate_settings_and_relation_type(self) -> "CreateCustomerProperty":
                 raise ValueError("settings must be DateAttributeSettings for DATETIME properties")
 
         # RELATION properties require relation_type
-        if prop_type == PropertyType.RELATION:
+        if prop_type == CustomerPropertyType.RELATION:
             if relation_type is None:
                 raise ValueError("relation_type is required for RELATION properties")
 
@@ -257,8 +260,8 @@ class UpdateCustomerProperty(BaseModel):
     description: str | None = None
     logo_props: Any | None = None
     sort_order: float | None = None
-    property_type: PropertyType | None = None
-    relation_type: RelationType | None = None
+    property_type: CustomerPropertyType | None = None
+    relation_type: CustomerRelationType | None = None
     is_required: bool | None = None
     default_value: list[str] | None = None
     settings: PropertySettings = None
@@ -272,11 +275,11 @@ class UpdateCustomerProperty(BaseModel):
     options: list[UpdateCustomerPropertyOption] | None = None
 
     @field_serializer("property_type")
-    def serialize_property_type(self, value: PropertyType) -> str | None:
+    def serialize_property_type(self, value: CustomerPropertyType) -> str | None:
         return value.value if value else None
 
     @field_serializer("relation_type")
-    def serialize_relation_type(self, value: RelationType) -> str | None:
+    def serialize_relation_type(self, value: CustomerRelationType) -> str | None:
         return value.value if value else None
 
     @model_validator(mode="after")
@@ -291,7 +294,7 @@ def validate_settings_and_relation_type(self) -> "UpdateCustomerProperty":
             return self
 
         # TEXT properties require TextAttributeSettings
-        if prop_type == PropertyType.TEXT:
+        if prop_type == CustomerPropertyType.TEXT:
             if settings is None:
                 raise ValueError(
                     "settings with TextAttributeSettings is required when updating to "
@@ -301,7 +304,7 @@ def validate_settings_and_relation_type(self) -> "UpdateCustomerProperty":
                 raise ValueError("settings must be TextAttributeSettings for TEXT properties")
 
         # DATETIME properties require DateAttributeSettings
-        if prop_type == PropertyType.DATETIME:
+        if prop_type == CustomerPropertyType.DATETIME:
             if settings is None:
                 raise ValueError(
                     "settings with DateAttributeSettings is required when updating to "
@@ -311,7 +314,7 @@ def validate_settings_and_relation_type(self) -> "UpdateCustomerProperty":
                 raise ValueError("settings must be DateAttributeSettings for DATETIME properties")
 
         # RELATION properties require relation_type
-        if prop_type == PropertyType.RELATION:
+        if prop_type == CustomerPropertyType.RELATION:
             if relation_type is None:
                 raise ValueError(
                     "relation_type is required when updating to RELATION property_type"

plane/models/enums.py

@@ -55,17 +55,19 @@
     "EMAIL",
     "FILE",
     "FORMULA",
+    "CASCADING",
 ]
-RelationTypeEnum = Literal["ISSUE", "USER", "RELEASE"]
+RelationTypeEnum = Literal["ISSUE", "USER", "RELEASE", "RICH_TEXT"]
 CycleStatusEnum = Literal["current", "upcoming", "completed", "draft", "incomplete"]
 # Deprecated alias for CycleStatusEnum. ``status`` is the canonical cycle filter
 # going forward; ``cycle_view`` is kept only for backward compatibility.
 CycleViewEnum = CycleStatusEnum
 
 
 # Proper Enum classes for better type safety and IDE support
-class PropertyType(Enum):
-    """Property type enumeration."""
+
+class PropertyType(str, Enum):
+    """Work item property types."""
 
     TEXT = "TEXT"
     DATETIME = "DATETIME"
@@ -77,17 +79,39 @@ class PropertyType(Enum):
     EMAIL = "EMAIL"
     FILE = "FILE"
     FORMULA = "FORMULA"
+    CASCADING = "CASCADING"
 
 
-class RelationType(Enum):
-    """Relation type enumeration."""
+class RelationType(str, Enum):
+    """Work item relation types."""
 
     ISSUE = "ISSUE"
     USER = "USER"
     RELEASE = "RELEASE"
     RICH_TEXT = "RICH_TEXT"
 
 
+class CustomerPropertyType(str, Enum):
+    """Customer property types -- the work item set without FORMULA and CASCADING."""
+
+    TEXT = "TEXT"
+    DATETIME = "DATETIME"
+    DECIMAL = "DECIMAL"
+    BOOLEAN = "BOOLEAN"
+    OPTION = "OPTION"
+    RELATION = "RELATION"
+    URL = "URL"
+    EMAIL = "EMAIL"
+    FILE = "FILE"
+
+
+class CustomerRelationType(str, Enum):
+    """Customer relation types -- a customer property can relate to a work item or a user."""
+
+    ISSUE = "ISSUE"
+    USER = "USER"
+
+
 class Priority(Enum):
     """Priority enumeration."""
 

plane/models/work_item_properties.py

@@ -257,6 +257,28 @@ class WorkItemPropertyValue(BaseModel):
     value_option: str | None = None
 
 
+class RichTextValue(BaseModel):
+    """The value of a rich text property: `property_type=RELATION`, `relation_type=RICH_TEXT`.
+
+    Plane requires an object here, not a bare HTML string, and sanitises the HTML
+    before storing it. Reads return the stored content in `value_detail`.
+    """
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+    description_html: str = Field(..., description="The content, as HTML, e.g. '<p>Notes</p>'")
+
+
+class RichTextValueDetail(BaseModel):
+    """The stored content of a rich text property value, as Plane returns it."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    id: str | None = Field(None, description="ID of the stored description; None when never set")
+    description_html: str = Field(..., description="The content as sanitised HTML")
+    description_stripped: str = Field("", description="The content as plain text")
+
+
 class CreateWorkItemPropertyValue(BaseModel):
     """Request model for creating/updating a work item property value.
 
@@ -267,6 +289,7 @@ class CreateWorkItemPropertyValue(BaseModel):
     - BOOLEAN: boolean (true/false)
     - OPTION/RELATION (single): string (UUID)
     - OPTION/RELATION (multi, when is_multi=True): list of strings (UUIDs) or single string
+    - RELATION with relation_type=RICH_TEXT: RichTextValue
 
     For multi-value properties (is_multi=True):
     - Accept either a single UUID string or a list of UUID strings
@@ -279,7 +302,7 @@ class CreateWorkItemPropertyValue(BaseModel):
 
     model_config = ConfigDict(extra="ignore", populate_by_name=True)
 
-    value: str | bool | int | float | list[str] = Field(
+    value: str | bool | int | float | list[str] | RichTextValue = Field(
         ..., description="The value to set for the property (type depends on property type)"
     )
     external_id: str | None = Field(None, description="Optional external identifier for syncing")
@@ -304,6 +327,11 @@ class WorkItemPropertyValueDetail(BaseModel):
         ..., description="The actual value, formatted according to property type"
     )
     value_type: str | None = Field(None, description="Type of the value")
+    value_detail: RichTextValueDetail | None = Field(
+        None,
+        description="The stored content of a rich text property. For rich text, `value` is "
+        "the ID of that stored content; the HTML is here.",
+    )
     external_id: str | None = Field(
         None, description="External identifier if synced with external system"
     )

tests/unit/test_customers.py

@@ -22,7 +22,7 @@
     UpdateCustomerPropertyOption,
     UpdateCustomerRequest,
 )
-from plane.models.enums import PropertyType
+from plane.models.enums import CustomerPropertyType, PropertyType, RelationType
 from plane.models.projects import Project
 from plane.models.work_item_property_configurations import TextAttributeSettings
 from plane.models.work_items import CreateWorkItem
@@ -660,3 +660,39 @@ def test_create_request_with_work_item_ids_links_them(
                 client.customers.requests.delete(workspace_slug, customer.id, req.id)
             except Exception:
                 pass
+
+
+class TestCustomerPropertyTypesOffline:
+    """Customer properties take Plane's customer set, not the work item one."""
+
+    BASE = {"name": "tier", "display_name": "Tier"}
+
+    @pytest.mark.parametrize("property_type", ["FORMULA", "CASCADING"])
+    def test_a_work_item_only_type_is_refused(self, property_type: str) -> None:
+        with pytest.raises(ValueError, match="property_type"):
+            CreateCustomerProperty(**self.BASE, property_type=property_type)
+
+    @pytest.mark.parametrize("relation_type", ["RELEASE", "RICH_TEXT"])
+    def test_a_work_item_only_relation_is_refused(self, relation_type: str) -> None:
+        with pytest.raises(ValueError, match="relation_type"):
+            CreateCustomerProperty(
+                **self.BASE, property_type="RELATION", relation_type=relation_type
+            )
+
+    def test_the_shared_enums_still_build_a_customer_property(self) -> None:
+        """Code written against PropertyType and RelationType keeps working, and a
+        property built that way still compares equal to the shared member."""
+        prop = CreateCustomerProperty(
+            **self.BASE, property_type=PropertyType.RELATION, relation_type=RelationType.USER
+        )
+
+        assert prop.property_type == PropertyType.RELATION
+        assert isinstance(prop.property_type, CustomerPropertyType)
+        assert prop.model_dump(exclude_none=True, include={"property_type", "relation_type"}) == {
+            "property_type": "RELATION",
+            "relation_type": "USER",
+        }
+
+    def test_a_shared_member_the_customer_set_lacks_is_still_refused(self) -> None:
+        with pytest.raises(ValueError, match="property_type"):
+            CreateCustomerProperty(**self.BASE, property_type=PropertyType.FORMULA)

tests/unit/test_work_item_properties.py

@@ -8,7 +8,11 @@
 from plane.models.work_item_properties import (
     CreateWorkItemProperty,
     CreateWorkItemPropertyOption,
+    CreateWorkItemPropertyValue,
+    RichTextValue,
     UpdateWorkItemProperty,
+    WorkItemProperty,
+    WorkItemPropertyValueDetail,
 )
 from plane.models.work_item_property_configurations import (
     DateAttributeSettings,
@@ -776,3 +780,73 @@ def test_attach_detach_property_to_type(
                 client.work_item_types.delete(workspace_slug, project.id, wit.id)
             except Exception:
                 pass
+
+
+class TestWorkItemPropertyTypesOffline:
+    """What the models accept and send. Offline, so it runs without a Plane instance."""
+
+    def test_a_cascading_property_parses(self) -> None:
+        """Plane returns CASCADING properties; the enum lacked the value, so listing a
+        workspace that had one raised ValidationError."""
+        prop = WorkItemProperty.model_validate(
+            {"id": "p", "property_type": "CASCADING", "display_name": "Region"}
+        )
+
+        assert prop.property_type == PropertyType.CASCADING
+
+    def test_rich_text_is_a_relation_type_not_a_property_type(self) -> None:
+        assert "RICH_TEXT" in {member.value for member in RelationType}
+        assert "RICH_TEXT" not in {member.value for member in PropertyType}
+
+
+class TestRichTextValueOffline:
+    """A rich text value is an object with description_html -- Plane answers a bare
+    string with 400 "Rich text value must be an object"."""
+
+    @pytest.fixture
+    def sent(self, monkeypatch: pytest.MonkeyPatch):
+        client = PlaneClient(api_key="k", base_url="http://plane.invalid")
+        payloads: list[dict] = []
+
+        def post(endpoint: str, data: dict | None = None, params: dict | None = None) -> dict:
+            payloads.append(data or {})
+            return {"id": "v", "property_id": "p", "issue_id": "w", "value": "desc-1"}
+
+        monkeypatch.setattr(client.work_item_properties.values, "_post", post)
+
+        def send(value) -> dict:
+            client.work_item_properties.values.create(
+                "ws", "p", "w", "prop", CreateWorkItemPropertyValue(value=value)
+            )
+            return payloads[-1]
+
+        return send
+
+    def test_a_rich_text_value_is_sent_as_an_object(self, sent) -> None:
+        assert sent(RichTextValue(description_html="<p>Notes</p>")) == {
+            "value": {"description_html": "<p>Notes</p>"}
+        }
+
+    def test_the_other_value_types_are_unchanged(self, sent) -> None:
+        assert sent("plain") == {"value": "plain"}
+        assert sent(True) == {"value": True}
+        assert sent(["a", "b"]) == {"value": ["a", "b"]}
+
+    def test_a_rich_text_read_carries_its_html_in_value_detail(self) -> None:
+        """`value` is the stored content's ID; the HTML is beside it."""
+        detail = WorkItemPropertyValueDetail.model_validate(
+            {
+                "id": "v",
+                "property_id": "p",
+                "issue_id": "w",
+                "value": "desc-1",
+                "value_detail": {
+                    "id": "desc-1",
+                    "description_html": "<p>Notes</p>",
+                    "description_stripped": "Notes",
+                },
+            }
+        )
+
+        assert detail.value == "desc-1"
+        assert detail.value_detail.description_html == "<p>Notes</p>"