canvas 0.63.0__py3-none-any.whl → 0.89.0__py3-none-any.whl

canvas_sdk/effects/fax/base.py

@@ -0,0 +1,77 @@
+from abc import ABC
+from typing import Any, Literal
+from uuid import UUID
+
+from pydantic_core import InitErrorDetails
+
+from canvas_sdk.effects import EffectType, _BaseEffect
+from canvas_sdk.v1.data import PracticeLocation
+
+
+class BaseFaxEffect(_BaseEffect, ABC):
+    """Base class for fax effects."""
+
+    class Meta:
+        effect_type = EffectType.UNKNOWN_EFFECT
+
+    recipient_name: str
+    recipient_fax_number: str
+    include_coversheet: bool = False
+    subject: str | None = None
+    comment: str | None = None
+    location_id: str | UUID | None = None
+
+    def _get_error_details(self, method: Literal["apply"]) -> list[InitErrorDetails]:
+        errors = super()._get_error_details(method)
+
+        if self.include_coversheet:
+            if not self.subject:
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        "subject is required when include_coversheet is True",
+                        self.subject,
+                    )
+                )
+            if not self.comment:
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        "comment is required when include_coversheet is True",
+                        self.comment,
+                    )
+                )
+            if self.location_id:
+                if not PracticeLocation.objects.filter(id=self.location_id).exists():
+                    errors.append(
+                        self._create_error_detail(
+                            "value",
+                            f"Practice Location {self.location_id} does not exist",
+                            self.location_id,
+                        )
+                    )
+            else:
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        "location_id is required when include_coversheet is True",
+                        self.location_id,
+                    )
+                )
+
+        return errors
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """Return the values of the fax effect."""
+        return {
+            "recipient_name": self.recipient_name,
+            "recipient_fax_number": self.recipient_fax_number,
+            "include_coversheet": self.include_coversheet,
+            "subject": self.subject,
+            "comment": self.comment,
+            "location_id": str(self.location_id) if self.location_id else None,
+        }
+
+
+__exports__ = ()

canvas_sdk/effects/fax/note.py

@@ -0,0 +1,42 @@
+from typing import Literal
+from uuid import UUID
+
+from pydantic_core import InitErrorDetails
+
+from canvas_generated.messages.effects_pb2 import EffectType
+from canvas_sdk.effects.fax.base import BaseFaxEffect
+from canvas_sdk.v1.data import Note
+
+
+class FaxNoteEffect(BaseFaxEffect):
+    """Fax note effect."""
+
+    class Meta:
+        effect_type = EffectType.FAX_NOTE
+
+    note_id: str | UUID
+
+    def _get_error_details(self, method: Literal["apply"]) -> list[InitErrorDetails]:
+        errors = super()._get_error_details(method)
+        if self.note_id and not Note.objects.filter(id=self.note_id).exists():
+            errors.append(
+                self._create_error_detail(
+                    "value",
+                    f"Note with ID {self.note_id} does not exist.",
+                    self.note_id,
+                )
+            )
+
+        return errors
+
+    @property
+    def values(self) -> dict[str, str]:
+        """Return the values of the note fax effect."""
+        values = super().values
+        return {
+            **values,
+            "note_id": str(self.note_id),
+        }
+
+
+__exports__ = ()

canvas_sdk/effects/metadata.py

@@ -1,9 +1,23 @@
 import json
+from dataclasses import dataclass
+from typing import Any
 
 from canvas_generated.messages.effects_pb2 import Effect
 from canvas_sdk.base import TrackableFieldsModel
 
 
+@dataclass
+class Metadata:
+    """A class representing a metadata."""
+
+    key: str
+    value: str
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the metadata to a dictionary."""
+        return {"key": self.key, "value": self.value}
+
+
 class BaseMetadata(TrackableFieldsModel):
     """Base class for metadata effects."""
 
@@ -23,4 +37,4 @@ class BaseMetadata(TrackableFieldsModel):
         )
 
 
-__exports__ = ()
+__exports__ = ("Metadata",)

canvas_sdk/effects/note/__init__.py

@@ -1,4 +1,9 @@
-from canvas_sdk.effects.note.appointment import Appointment, ScheduleEvent
+from canvas_sdk.effects.note.appointment import (
+    AddAppointmentLabel,
+    Appointment,
+    RemoveAppointmentLabel,
+    ScheduleEvent,
+)
 from canvas_sdk.effects.note.base import AppointmentIdentifier
 from canvas_sdk.effects.note.note import Note
 
@@ -7,4 +12,6 @@ __all__ = __exports__ = (
     "Note",
     "Appointment",
     "ScheduleEvent",
+    "AddAppointmentLabel",
+    "RemoveAppointmentLabel",
 )

canvas_sdk/effects/note/appointment.py

@@ -1,12 +1,17 @@
 import json
-from typing import Any
+from typing import Annotated, Any
 from uuid import UUID
 
+from django.db.models import Count
+from pydantic import Field
 from pydantic_core import InitErrorDetails
 
-from canvas_sdk.effects import Effect
+from canvas_sdk.base import TrackableFieldsModel
+from canvas_sdk.effects import Effect, EffectType
+from canvas_sdk.effects.base import _BaseEffect
 from canvas_sdk.effects.note.base import AppointmentABC
-from canvas_sdk.v1.data import NoteType, Patient
+from canvas_sdk.v1.data import Appointment as AppointmentDataModel
+from canvas_sdk.v1.data import AppointmentLabel, NoteType, Patient
 from canvas_sdk.v1.data.note import NoteTypeCategories
 
 
@@ -127,6 +132,7 @@ class Appointment(AppointmentABC):
         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 | None): The ID of the patient.
+        labels (conset[str] | None): A set of label names to apply to the appointment.
     """
 
     class Meta:
@@ -135,6 +141,13 @@ class Appointment(AppointmentABC):
     appointment_note_type_id: UUID | str | None = None
     meeting_link: str | None = None
     patient_id: str | None = None
+    labels: (
+        Annotated[
+            set[Annotated[str, Field(min_length=1, max_length=50)]],
+            Field(min_length=1, max_length=3),
+        ]
+        | None
+    ) = None
 
     def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
         """
@@ -186,9 +199,11 @@ class Appointment(AppointmentABC):
 
         if self.appointment_note_type_id:
             try:
-                category, is_scheduleable = NoteType.objects.values_list(
-                    "category", "is_scheduleable"
-                ).get(id=self.appointment_note_type_id)
+                category, is_scheduleable = (
+                    NoteType.objects.values_list("category", "is_scheduleable")
+                    .filter(is_active=True)
+                    .get(id=self.appointment_note_type_id)
+                )
                 if category != NoteTypeCategories.ENCOUNTER:
                     errors.append(
                         self._create_error_detail(
@@ -215,8 +230,39 @@ class Appointment(AppointmentABC):
                     )
                 )
 
+        if method == "update" and self.labels and self.instance_id:
+            existing_count = AppointmentLabel.objects.filter(
+                appointment__id=self.instance_id
+            ).count()
+            if existing_count + len(self.labels) > 3:
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        f"Limit reached: Only 3 appointment labels allowed. Attempted to add {len(self.labels)} label(s) to appointment with {existing_count} existing label(s).",
+                        sorted(self.labels),
+                    )
+                )
+
         return errors
 
+    @property
+    def values(self) -> dict:
+        """
+        Returns a dictionary of modified attributes with type-specific transformations.
+        """
+        values = super().values
+        # Convert labels set to list for JSON serialization
+        # This is necessary because:
+        # 1. The labels field is defined as a conset (constrained set) for validation
+        # 2. JSON cannot serialize Python sets directly - it only supports lists, dicts, strings, numbers, booleans, and None
+        # 3. When the effect payload is serialized to JSON in the base Effect class, it would fail with:
+        #    "TypeError: Object of type set is not JSON serializable"
+        # 4. Converting to list maintains the same data while making it JSON-compatible
+        # 5. Sort the labels to ensure consistent ordering for tests and API responses
+        if self.labels is not None:
+            values["labels"] = sorted(self.labels)
+        return values
+
     def cancel(self) -> Effect:
         """Send a CANCEL effect for the appointment."""
         self._validate_before_effect("cancel")
@@ -230,4 +276,86 @@ class Appointment(AppointmentABC):
         )
 
 
-__exports__ = ("ScheduleEvent", "Appointment")
+class _AppointmentLabelBase(_BaseEffect, TrackableFieldsModel):
+    """
+    Base class for appointment label effects.
+
+    Attributes:
+        appointment_id (UUID | str): The ID of the appointment.
+        labels (conset[str]): A set of label names (1-3 labels allowed).
+    """
+
+    appointment_id: str
+    labels: Annotated[set[str], Field(min_length=1, max_length=3)]
+
+    @property
+    def values(self) -> dict:
+        """The effect's values."""
+        result = {
+            "appointment_id": str(self.appointment_id),
+            "labels": sorted(self.labels),
+        }
+        return result
+
+
+class AddAppointmentLabel(_AppointmentLabelBase):
+    """
+    Effect to add one or more labels to an appointment.
+    """
+
+    class Meta:
+        effect_type = EffectType.ADD_APPOINTMENT_LABEL
+
+    def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
+        """Validate that the appointment does not exceed the 3-label limit."""
+        errors = super()._get_error_details(method)
+
+        appointment_label_count = (
+            AppointmentDataModel.objects.filter(id=self.appointment_id)
+            .annotate(label_count=Count("labels"))
+            .values_list("label_count", flat=True)
+            .first()
+        )
+
+        # note that appointment_label_count will be None if the appointment doesn't exist
+        # and appointment_label_count will be 0 if the appointment exists but has no labels
+        if appointment_label_count is None:
+            errors.append(
+                self._create_error_detail(
+                    "value",
+                    f"Appointment {self.appointment_id} does not exist",
+                    self.appointment_id,
+                )
+            )
+        elif appointment_label_count + len(self.labels) > 3:
+            errors.append(
+                self._create_error_detail(
+                    "value",
+                    f"Limit reached: Only 3 appointment labels allowed. "
+                    f"Attempted to add {len(self.labels)} label(s) to appointment with "
+                    f"{appointment_label_count} existing label(s).",
+                    sorted(self.labels),
+                )
+            )
+        return errors
+
+
+class RemoveAppointmentLabel(_AppointmentLabelBase):
+    """
+    Effect to remove one or more labels from an appointment.
+
+    Attributes:
+        appointment_id (UUID | str): The ID of the appointment to remove labels from.
+        labels (list[str]): A list of label names to remove.
+    """
+
+    class Meta:
+        effect_type = EffectType.REMOVE_APPOINTMENT_LABEL
+
+
+__exports__ = (
+    "ScheduleEvent",
+    "Appointment",
+    "AddAppointmentLabel",
+    "RemoveAppointmentLabel",
+)

canvas_sdk/effects/note/base.py

@@ -239,5 +239,22 @@ class AppointmentABC(NoteOrAppointmentABC, ABC):
 
         return values
 
+    def reschedule(self) -> Effect:
+        """Send a RESCHEDULE effect for the 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"RESCHEDULE_{self.Meta.effect_type}",
+            payload=json.dumps(
+                {
+                    "data": self.values,
+                }
+            ),
+        )
+
 
 __exports__ = ("AppointmentIdentifier", "NoteOrAppointmentABC", "AppointmentABC")

canvas_sdk/effects/note/message.py

@@ -1,4 +1,5 @@
 import json
+from datetime import datetime
 from typing import Any
 from uuid import UUID
 
@@ -19,9 +20,10 @@ class Message(TrackableFieldsModel):
         effect_type = "MESSAGE"
 
     message_id: str | UUID | None = None
-    content: str
+    content: str | None
     sender_id: str | UUID
     recipient_id: str | UUID
+    read: datetime | None = None
 
     def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
         errors = super()._get_error_details(method)
@@ -68,21 +70,27 @@ class Message(TrackableFieldsModel):
                             self.message_id,
                         )
                     )
-        elif (
-            method
-            in (
-                "create",
-                "create_and_send",
-            )
-            and self.message_id
+        elif method in (
+            "create",
+            "create_and_send",
         ):
-            errors.append(
-                self._create_error_detail(
-                    "value",
-                    "Can't set message ID when creating a message.",
-                    self.message_id,
+            if not self.content or self.content.strip() == "":
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        "Message content cannot be empty.",
+                        self.content,
+                    )
+                )
+
+            if self.message_id:
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        "Can't set message ID when creating a message.",
+                        self.message_id,
+                    )
                 )
-            )
 
         return errors
 

canvas_sdk/effects/note/note.py

@@ -1,13 +1,33 @@
 import datetime
+import json
 from typing import Any
 from uuid import UUID
 
 from pydantic_core import InitErrorDetails
 
+from canvas_generated.messages.effects_pb2 import EffectType
+from canvas_sdk.effects import Effect
 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
+from canvas_sdk.v1.data.note import NoteStates, NoteTypeCategories
+
+TRANSITION_STATE_MATRIX = {
+    NoteStates.NEW: [NoteStates.LOCKED, NoteStates.PUSHED],
+    NoteStates.LOCKED: [NoteStates.SIGNED, NoteStates.UNLOCKED],
+    NoteStates.UNLOCKED: [NoteStates.LOCKED, NoteStates.PUSHED],
+    NoteStates.SIGNED: [NoteStates.UNLOCKED, NoteStates.SIGNED],
+    NoteStates.PUSHED: [NoteStates.LOCKED, NoteStates.PUSHED],
+}
+
+ACTION_STATE_MATRIX = {
+    "lock": NoteStates.LOCKED,
+    "unlock": NoteStates.UNLOCKED,
+    "sign": NoteStates.SIGNED,
+    "push_charges": NoteStates.PUSHED,
+    "check_in": NoteStates.CONVERTED,
+    "no_show": NoteStates.NOSHOW,
+}
 
 
 class Note(NoteOrAppointmentABC):
@@ -28,6 +48,82 @@ class Note(NoteOrAppointmentABC):
     patient_id: str | None = None
     title: str | None = None
 
+    def push_charges(self) -> Effect:
+        """Pushes BillingLineItems from the Note to the associated Claim. Identicial to clicking the Push Charges button in the note footer."""
+        self._validate_before_effect("push_charges")
+        return Effect(
+            type=EffectType.PUSH_NOTE_CHARGES,
+            payload=json.dumps({"data": {"note": str(self.instance_id)}}),
+        )
+
+    def unlock(self) -> Effect:
+        """Unlocks the note to allow further edits."""
+        self._validate_before_effect("unlock")
+        return Effect(
+            type=EffectType.UNLOCK_NOTE,
+            payload=json.dumps({"data": {"note": str(self.instance_id)}}),
+        )
+
+    def lock(self) -> Effect:
+        """Locks the note to prevent further edits."""
+        self._validate_before_effect("lock")
+        return Effect(
+            type=EffectType.LOCK_NOTE,
+            payload=json.dumps({"data": {"note": str(self.instance_id)}}),
+        )
+
+    def sign(self) -> Effect:
+        """Signs the note."""
+        self._validate_before_effect("sign")
+        return Effect(
+            type=EffectType.SIGN_NOTE,
+            payload=json.dumps({"data": {"note": str(self.instance_id)}}),
+        )
+
+    def check_in(self) -> Effect:
+        """Mark the note as checked-in."""
+        self._validate_before_effect("check_in")
+        return Effect(
+            type=EffectType.CHECK_IN_NOTE,
+            payload=json.dumps({"data": {"note": str(self.instance_id)}}),
+        )
+
+    def no_show(self) -> Effect:
+        """Mark the note as no-show."""
+        self._validate_before_effect("no_show")
+        return Effect(
+            type=EffectType.NO_SHOW_NOTE,
+            payload=json.dumps({"data": {"note": str(self.instance_id)}}),
+        )
+
+    def _validate_state_transition(
+        self, note: NoteModel, next_state: NoteStates
+    ) -> tuple[bool, InitErrorDetails | None]:
+        """Validates state transitions for the note."""
+        current_state = note.current_state.state if note.current_state else None
+
+        if not current_state:
+            return False, self._create_error_detail(
+                "value", "Unsupported state transitions", next_state
+            )
+
+        is_sig_required = note.note_type_version.is_sig_required
+        if next_state == NoteStates.SIGNED and not is_sig_required:
+            return False, self._create_error_detail(
+                "value", "Cannot sign a note that does not require a signature.", next_state
+            )
+
+        if (
+            next_state == NoteStates.CONVERTED or next_state == NoteStates.NOSHOW
+        ) and note.note_type_version.category != NoteTypeCategories.APPOINTMENT:
+            return False, self._create_error_detail(
+                "value",
+                "Only appointments can be checked in or marked as no-show.",
+                next_state,
+            )
+
+        return True, None
+
     def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
         """
         Validates the note type category and returns a list of error details if validation fails.
@@ -40,6 +136,59 @@ class Note(NoteOrAppointmentABC):
         """
         errors = super()._get_error_details(method)
 
+        if method in ACTION_STATE_MATRIX:
+            if not self.instance_id:
+                errors.append(
+                    self._create_error_detail(
+                        "missing",
+                        "Field 'instance_id' is required.",
+                        None,
+                    )
+                )
+                return errors
+            elif not (note := NoteModel.objects.filter(id=self.instance_id).first()):
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        f"Note with ID {self.instance_id} does not exist.",
+                        self.instance_id,
+                    )
+                )
+                return errors
+
+            if note.note_type_version.category in (
+                NoteTypeCategories.LETTER,
+                NoteTypeCategories.MESSAGE,
+            ):
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        f"Note with note type {note.note_type_version.name} cannot perform action '{method}'.",
+                        note.note_type_version,
+                    )
+                )
+                return errors
+
+            if method == "push_charges" and (
+                not note.note_type_version or not note.note_type_version.is_billable
+            ):
+                errors.append(
+                    self._create_error_detail(
+                        "value",
+                        f"Note with note type {note.note_type_version} is not billable and has no associated claim.",
+                        note.note_type_version,
+                    )
+                )
+                return errors
+
+            if method in ACTION_STATE_MATRIX:
+                _, error = self._validate_state_transition(note, ACTION_STATE_MATRIX[method])
+
+                if error:
+                    errors.append(error)
+
+            return errors
+
         if method == "create":
             if not self.note_type_id:
                 errors.append(

canvas_sdk/effects/observation/__init__.py

@@ -0,0 +1,11 @@
+from canvas_sdk.effects.observation.base import (
+    CodingData,
+    Observation,
+    ObservationComponentData,
+)
+
+__all__ = __exports__ = (
+    "Observation",
+    "CodingData",
+    "ObservationComponentData",
+)