canvas 0.42.0__py3-none-any.whl → 0.44.0__py3-none-any.whl

canvas_sdk/effects/note/appointment.py

@@ -1,8 +1,10 @@
+import json
 from typing import Any
 from uuid import UUID
 
 from pydantic_core import InitErrorDetails
 
+from canvas_sdk.effects import Effect
 from canvas_sdk.effects.note.base import AppointmentABC
 from canvas_sdk.v1.data import NoteType, Patient
 from canvas_sdk.v1.data.note import NoteTypeCategories
@@ -13,7 +15,7 @@ class ScheduleEvent(AppointmentABC):
     Effect to create a schedule event.
 
     Attributes:
-        note_type_id (UUID | str): The ID of the note type.
+        note_type_id (UUID | str | None): The ID of the note type.
         patient_id (str | None): The ID of the patient, if applicable.
         description (str | None): The description of the schedule event, if applicable.
     """
@@ -21,7 +23,7 @@ class ScheduleEvent(AppointmentABC):
     class Meta:
         effect_type = "SCHEDULE_EVENT"
 
-    note_type_id: UUID | str
+    note_type_id: UUID | str | None = None
     patient_id: str | None = None
     description: str | None = None
 
@@ -37,68 +39,102 @@ class ScheduleEvent(AppointmentABC):
         """
         errors = super()._get_error_details(method)
 
-        note_type = (
-            NoteType.objects.values("category", "is_patient_required", "allow_custom_title")
-            .filter(id=self.note_type_id)
-            .first()
-        )
-
-        if not note_type:
+        # note_type_id is required for create
+        if method == "create" and not self.note_type_id:
             errors.append(
                 self._create_error_detail(
-                    "value",
-                    f"Note type with ID {self.note_type_id} does not exist.",
-                    self.note_type_id,
+                    "missing",
+                    "Field 'note_type_id' is required to create a schedule event.",
+                    None,
                 )
             )
             return errors
 
-        if note_type["category"] != NoteTypeCategories.SCHEDULE_EVENT:
-            errors.append(
-                self._create_error_detail(
-                    "value",
-                    f"Schedule event note type must be of type: {NoteTypeCategories.SCHEDULE_EVENT}.",
-                    self.note_type_id,
-                )
+        if self.note_type_id:
+            note_type = (
+                NoteType.objects.values("category", "is_patient_required", "allow_custom_title")
+                .filter(id=self.note_type_id)
+                .first()
             )
 
-        if note_type["is_patient_required"] and not self.patient_id:
-            errors.append(
-                self._create_error_detail(
-                    "value",
-                    "Patient ID is required for this note type.",
-                    self.note_type_id,
+            if not note_type:
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        f"Note type with ID {self.note_type_id} does not exist.",
+                        self.note_type_id,
+                    )
+                )
+                return errors
+
+            if note_type["category"] != NoteTypeCategories.SCHEDULE_EVENT:
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        f"Schedule event note type must be of type: {NoteTypeCategories.SCHEDULE_EVENT}.",
+                        self.note_type_id,
+                    )
+                )
+
+            if note_type["is_patient_required"] and not self.patient_id:
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        "Patient ID is required for this note type.",
+                        self.note_type_id,
+                    )
+                )
+
+            if not note_type["allow_custom_title"] and self.description:
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        "Description is not allowed for this note type.",
+                        self.note_type_id,
+                    )
                 )
-            )
 
-        if not note_type["allow_custom_title"] and self.description:
+        # Validate patient exists if provided
+        if self.patient_id and not Patient.objects.filter(id=self.patient_id).exists():
             errors.append(
                 self._create_error_detail(
                     "value",
-                    "Description is not allowed for this note type.",
-                    self.note_type_id,
+                    f"Patient with ID {self.patient_id} does not exist.",
+                    self.patient_id,
                 )
             )
 
         return errors
 
+    def delete(self) -> Effect:
+        """Send a DELETE effect for the schedule event."""
+        self._validate_before_effect("delete")
+        return Effect(
+            type=f"DELETE_{self.Meta.effect_type}",
+            payload=json.dumps(
+                {
+                    "data": self.values,
+                }
+            ),
+        )
+
 
 class Appointment(AppointmentABC):
     """
-    Effect to create an appointment.
+    Effect to create or update an appointment.
 
     Attributes:
-        appointment_note_type_id (UUID | str): The ID of the appointment note type.
+        appointment_note_type_id (UUID | str | None): The ID of the appointment note type.
         meeting_link (str | None): The meeting link for the appointment, if any.
-        patient_id (str): The ID of the patient.
+        patient_id (str | None): The ID of the patient.
     """
 
     class Meta:
         effect_type = "APPOINTMENT"
 
-    appointment_note_type_id: UUID | str
+    appointment_note_type_id: UUID | str | None = None
     meeting_link: str | None = None
-    patient_id: str
+    patient_id: str | None = None
 
     def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
         """
@@ -112,37 +148,86 @@ class Appointment(AppointmentABC):
         """
         errors = super()._get_error_details(method)
 
-        if not Patient.objects.filter(id=self.patient_id).exists():
-            errors.append(
-                self._create_error_detail(
-                    "value",
-                    "Patient with ID {self.patient_id} does not exist.",
-                    self.patient_id,
+        if method == "create":
+            if not self.appointment_note_type_id:
+                errors.append(
+                    self._create_error_detail(
+                        "missing",
+                        "Field 'appointment_note_type_id' is required to create an appointment.",
+                        None,
+                    )
+                )
+            if not self.patient_id:
+                errors.append(
+                    self._create_error_detail(
+                        "missing",
+                        "Field 'patient_id' is required to create an appointment.",
+                        None,
+                    )
                 )
-            )
 
-        category, is_scheduleable = NoteType.objects.values_list("category", "is_scheduleable").get(
-            id=self.appointment_note_type_id
-        )
-        if category != NoteTypeCategories.ENCOUNTER:
+        if method == "update" and self.patient_id:
             errors.append(
                 self._create_error_detail(
                     "value",
-                    f"Appointment note type must be of type, {NoteTypeCategories.ENCOUNTER} but got: {category}.",
-                    self.appointment_note_type_id,
+                    "Field 'patient_id' cannot be updated for an existing appointment.",
+                    None,
                 )
             )
 
-        if not is_scheduleable:
+        if self.patient_id and not Patient.objects.filter(id=self.patient_id).exists():
             errors.append(
                 self._create_error_detail(
                     "value",
-                    "Appointment note type must be scheduleable.",
-                    self.appointment_note_type_id,
+                    "Patient with ID {self.patient_id} does not exist.",
+                    self.patient_id,
                 )
             )
 
+        if self.appointment_note_type_id:
+            try:
+                category, is_scheduleable = NoteType.objects.values_list(
+                    "category", "is_scheduleable"
+                ).get(id=self.appointment_note_type_id)
+                if category != NoteTypeCategories.ENCOUNTER:
+                    errors.append(
+                        self._create_error_detail(
+                            "value",
+                            f"Appointment note type must be of type, {NoteTypeCategories.ENCOUNTER} but got: {category}.",
+                            self.appointment_note_type_id,
+                        )
+                    )
+
+                if not is_scheduleable:
+                    errors.append(
+                        self._create_error_detail(
+                            "value",
+                            "Appointment note type must be scheduleable.",
+                            self.appointment_note_type_id,
+                        )
+                    )
+            except NoteType.DoesNotExist:
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        f"Note type with ID {self.appointment_note_type_id} does not exist.",
+                        self.appointment_note_type_id,
+                    )
+                )
+
         return errors
 
+    def cancel(self) -> Effect:
+        """Send a CANCEL effect for the appointment."""
+        self._validate_before_effect("cancel")
+        return Effect(
+            type=f"CANCEL_{self.Meta.effect_type}",
+            payload=json.dumps(
+                {
+                    "data": self.values,
+                }
+            ),
+        )
+
 
 __exports__ = ("ScheduleEvent", "Appointment")

canvas_sdk/effects/note/base.py

@@ -10,7 +10,7 @@ from pydantic_core import InitErrorDetails
 from canvas_generated.messages.effects_pb2 import Effect
 from canvas_sdk.base import TrackableFieldsModel
 from canvas_sdk.v1.data import PracticeLocation, Staff
-from canvas_sdk.v1.data.appointment import AppointmentProgressStatus
+from canvas_sdk.v1.data.appointment import Appointment, AppointmentProgressStatus
 
 
 @dataclass
@@ -32,6 +32,7 @@ class NoteOrAppointmentABC(TrackableFieldsModel, ABC):
     Base class for all note effects.
 
     Attributes:
+        instance_id (UUID | str): The unique identifier for the note or appointment instance.
         practice_location_id (UUID | str): The ID of the practice location.
         provider_id (str): The ID of the provider.
     """
@@ -39,8 +40,9 @@ class NoteOrAppointmentABC(TrackableFieldsModel, ABC):
     class Meta:
         effect_type = None
 
-    practice_location_id: UUID | str
-    provider_id: str
+    instance_id: UUID | str | None = None
+    practice_location_id: UUID | str | None = None
+    provider_id: str | None = None
 
     def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
         """
@@ -54,7 +56,46 @@ class NoteOrAppointmentABC(TrackableFieldsModel, ABC):
         """
         errors = super()._get_error_details(method)
 
-        if not PracticeLocation.objects.filter(id=self.practice_location_id).exists():
+        if method == "create":
+            if self.instance_id:
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        "Instance ID should not be provided for create effects.",
+                        self.instance_id,
+                    )
+                )
+            if not self.practice_location_id:
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        "Practice location ID is required.",
+                        self.practice_location_id,
+                    )
+                )
+            if not self.provider_id:
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        "Provider ID is required.",
+                        self.provider_id,
+                    )
+                )
+
+        else:
+            if not self.instance_id:
+                errors.append(
+                    self._create_error_detail(
+                        "missing",
+                        "Field 'instance_id' is required to update or cancel/delete a note or appointment.",
+                        None,
+                    )
+                )
+
+        if (
+            self.practice_location_id
+            and not PracticeLocation.objects.filter(id=self.practice_location_id).exists()
+        ):
             errors.append(
                 self._create_error_detail(
                     "value",
@@ -63,7 +104,7 @@ class NoteOrAppointmentABC(TrackableFieldsModel, ABC):
                 )
             )
 
-        if not Staff.objects.filter(id=self.provider_id).exists():
+        if self.provider_id and not Staff.objects.filter(id=self.provider_id).exists():
             errors.append(
                 self._create_error_detail(
                     "value",
@@ -75,7 +116,7 @@ class NoteOrAppointmentABC(TrackableFieldsModel, ABC):
         return errors
 
     def create(self) -> Effect:
-        """Originate a new command in the note body."""
+        """Send a CREATE effect for the note or appointment."""
         self._validate_before_effect("create")
         return Effect(
             type=f"CREATE_{self.Meta.effect_type}",
@@ -86,10 +127,27 @@ class NoteOrAppointmentABC(TrackableFieldsModel, ABC):
             ),
         )
 
+    def update(self) -> Effect:
+        """Send an UPDATE effect for the note or appointment."""
+        self._validate_before_effect("update")
+
+        # Check if any fields were actually modified
+        if self._dirty_keys == {"instance_id"}:
+            raise ValueError("No fields have been modified. Nothing to update.")
+
+        return Effect(
+            type=f"UPDATE_{self.Meta.effect_type}",
+            payload=json.dumps(
+                {
+                    "data": self.values,
+                }
+            ),
+        )
+
 
 class AppointmentABC(NoteOrAppointmentABC, ABC):
     """
-    Base class for appointment creation effects.
+    Base class for appointment create/update effects.
 
     Attributes:
         start_time (datetime.datetime): The start time of the appointment.
@@ -105,11 +163,48 @@ class AppointmentABC(NoteOrAppointmentABC, ABC):
         "external_identifiers",
     ]
 
-    start_time: datetime.datetime
-    duration_minutes: int
+    start_time: datetime.datetime | None = None
+    duration_minutes: int | None = None
     status: AppointmentProgressStatus | None = None
     external_identifiers: list[AppointmentIdentifier] | None = None
 
+    def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
+        """Validates the appointment instance and returns a list of error details if validation fails."""
+        errors = super()._get_error_details(method)
+
+        if method == "create":
+            # Additional required fields for appointment creation
+            if not self.start_time:
+                errors.append(
+                    self._create_error_detail(
+                        "missing",
+                        "Field 'start_time' is required to create an appointment.",
+                        None,
+                    )
+                )
+
+            if not self.duration_minutes:
+                errors.append(
+                    self._create_error_detail(
+                        "missing",
+                        "Field 'duration_minutes' is required to create an appointment.",
+                        None,
+                    )
+                )
+
+        # Validate appointment exists for update/delete
+        else:
+            if self.instance_id and not Appointment.objects.filter(id=self.instance_id).exists():
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        f"Appointment with ID {self.instance_id} does not exist.",
+                        self.instance_id,
+                    )
+                )
+
+        return errors
+
     @property
     def values(self) -> dict:
         """
@@ -117,7 +212,10 @@ class AppointmentABC(NoteOrAppointmentABC, ABC):
         """
         values = super().values
 
-        if self.external_identifiers:
+        # Handle external_identifiers separately since it's excluded from dirty tracking
+        # because it can be a complex type
+        # Only include if explicitly set (not None)
+        if self.external_identifiers is not None:
             values["external_identifiers"] = [
                 {"system": identifier.system, "value": identifier.value}
                 for identifier in self.external_identifiers

canvas_sdk/effects/note/note.py

@@ -5,6 +5,7 @@ from uuid import UUID
 from pydantic_core import InitErrorDetails
 
 from canvas_sdk.effects.note.base import NoteOrAppointmentABC
+from canvas_sdk.v1.data import Note as NoteModel
 from canvas_sdk.v1.data import NoteType, Patient
 from canvas_sdk.v1.data.note import NoteTypeCategories
 
@@ -22,9 +23,10 @@ class Note(NoteOrAppointmentABC):
     class Meta:
         effect_type = "NOTE"
 
-    note_type_id: UUID | str
-    datetime_of_service: datetime.datetime
-    patient_id: str
+    note_type_id: UUID | str | None = None
+    datetime_of_service: datetime.datetime | None = None
+    patient_id: str | None = None
+    title: str | None = None
 
     def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
         """
@@ -38,33 +40,90 @@ class Note(NoteOrAppointmentABC):
         """
         errors = super()._get_error_details(method)
 
-        note_type_category = (
-            NoteType.objects.values_list("category", flat=True).filter(id=self.note_type_id).first()
-        )
+        if method == "create":
+            if not self.note_type_id:
+                errors.append(
+                    self._create_error_detail(
+                        "missing",
+                        "Field 'note_type_id' is required to create a note.",
+                        None,
+                    )
+                )
 
-        if not note_type_category:
-            errors.append(
-                self._create_error_detail(
-                    "value",
-                    f"Note type with ID {self.note_type_id} does not exist.",
-                    self.note_type_id,
+            if not self.datetime_of_service:
+                errors.append(
+                    self._create_error_detail(
+                        "missing",
+                        "Field 'datetime_of_service' is required to create a note.",
+                        None,
+                    )
                 )
-            )
-        elif note_type_category in (
-            NoteTypeCategories.APPOINTMENT,
-            NoteTypeCategories.SCHEDULE_EVENT,
-            NoteTypeCategories.MESSAGE,
-            NoteTypeCategories.LETTER,
-        ):
+
+            if not self.patient_id:
+                errors.append(
+                    self._create_error_detail(
+                        "missing",
+                        "Field 'patient_id' is required to create a note.",
+                        None,
+                    )
+                )
+        elif method == "update":
+            if self.note_type_id:
+                errors.append(
+                    self._create_error_detail(
+                        "invalid",
+                        "Field 'note_type_id' cannot be updated for a note.",
+                        self.note_type_id,
+                    )
+                )
+            if self.patient_id:
+                errors.append(
+                    self._create_error_detail(
+                        "invalid",
+                        "Field 'patient_id' cannot be updated for a note.",
+                        self.patient_id,
+                    )
+                )
+
+        if self.instance_id and not NoteModel.objects.filter(id=self.instance_id).exists():
             errors.append(
                 self._create_error_detail(
                     "value",
-                    f"Visit note type cannot be of type: {note_type_category}.",
-                    self.note_type_id,
+                    f"Note with ID {self.instance_id} does not exist.",
+                    self.instance_id,
                 )
             )
 
-        if not Patient.objects.filter(id=self.patient_id).exists():
+        if self.note_type_id:
+            note_type_category = (
+                NoteType.objects.values_list("category", flat=True)
+                .filter(id=self.note_type_id)
+                .first()
+            )
+
+            if not note_type_category:
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        f"Note type with ID {self.note_type_id} does not exist.",
+                        self.note_type_id,
+                    )
+                )
+            elif note_type_category in (
+                NoteTypeCategories.APPOINTMENT,
+                NoteTypeCategories.SCHEDULE_EVENT,
+                NoteTypeCategories.MESSAGE,
+                NoteTypeCategories.LETTER,
+            ):
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        f"Visit note type cannot be of type: {note_type_category}.",
+                        self.note_type_id,
+                    )
+                )
+
+        if self.patient_id and not Patient.objects.filter(id=self.patient_id).exists():
             errors.append(
                 self._create_error_detail(
                     "value",

canvas_sdk/effects/patient/__init__.py

@@ -1,3 +1,11 @@
-from canvas_sdk.effects.patient.base import Patient, PatientContactPoint
+from canvas_sdk.effects.patient.base import Patient, PatientContactPoint, PatientExternalIdentifier
+from canvas_sdk.effects.patient.create_patient_external_identifier import (
+    CreatePatientExternalIdentifier,
+)
 
-__all__ = __exports__ = ("Patient", "PatientContactPoint")
+__all__ = __exports__ = (
+    "Patient",
+    "PatientContactPoint",
+    "PatientExternalIdentifier",
+    "CreatePatientExternalIdentifier",
+)

canvas_sdk/effects/patient/base.py

@@ -32,6 +32,21 @@ class PatientContactPoint:
         }
 
 
+@dataclass
+class PatientExternalIdentifier:
+    """A class representing a patient external identifier."""
+
+    value: str
+    system: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the external identifier to a dictionary."""
+        return {
+            "system": self.system,
+            "value": self.value,
+        }
+
+
 class Patient(TrackableFieldsModel):
     """Effect to create a Patient record."""
 
@@ -53,6 +68,7 @@ class Patient(TrackableFieldsModel):
     default_provider_id: str | None = None
     previous_names: list[str] | None = None
     contact_points: list[PatientContactPoint] | None = None
+    external_identifiers: list[PatientExternalIdentifier] | None = None
 
     @property
     def values(self) -> dict[str, Any]:
@@ -75,6 +91,9 @@ class Patient(TrackableFieldsModel):
             "contact_points": [cp.to_dict() for cp in self.contact_points]
             if self.contact_points
             else None,
+            "external_identifiers": [ids.to_dict() for ids in self.external_identifiers]
+            if self.external_identifiers
+            else None,
         }
 
     def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
@@ -120,4 +139,4 @@ class Patient(TrackableFieldsModel):
         )
 
 
-__exports__ = ("Patient", "PatientContactPoint")
+__exports__ = ("Patient", "PatientContactPoint", "PatientExternalIdentifier")

canvas_sdk/effects/patient/create_patient_external_identifier.py

@@ -0,0 +1,40 @@
+import json
+
+from canvas_generated.messages.effects_pb2 import Effect
+from canvas_sdk.base import TrackableFieldsModel
+
+
+class CreatePatientExternalIdentifier(TrackableFieldsModel):
+    """Effect to create a Patient External Identifier record."""
+
+    class Meta:
+        effect_type = "PATIENT_EXTERNAL_IDENTIFIER"
+
+    value: str
+    system: str | None = None
+    patient_id: str | None = None
+
+    @property
+    def values(self) -> dict[str, str | None]:
+        """Return the values of the external identifier."""
+        return {
+            "value": self.value,
+            "system": self.system,
+            "patient_id": self.patient_id,
+        }
+
+    def create(self) -> Effect:
+        """Create a new Patient External Identifier."""
+        self._validate_before_effect("create")
+
+        return Effect(
+            type=f"CREATE_{self.Meta.effect_type}",
+            payload=json.dumps(
+                {
+                    "data": self.values,
+                }
+            ),
+        )
+
+
+__exports__ = ("CreatePatientExternalIdentifier",)