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

canvas_sdk/commands/commands/review/base.py

@@ -0,0 +1,72 @@
+from enum import StrEnum
+from typing import Any
+from uuid import UUID
+
+from django.core.exceptions import ImproperlyConfigured
+from django.db.models import Q
+from pydantic_core import InitErrorDetails
+
+from canvas_sdk.commands.base import _BaseCommand
+
+
+class ReportReviewCommunicationMethod(StrEnum):
+    """Communication methods for a report review."""
+
+    DELEGATED_CALL_CAN_LEAVE_MESSAGE = "DM"
+    DELEGATED_CALL_NEED_ANSWER = "DA"
+    DELEGATED_LETTER = "DL"
+    ALREADY_LEFT_MESSAGE = "AM"
+    ALREADY_REVIEWED_WITH_PATIENT = "AR"
+
+
+class ReviewMode(StrEnum):
+    """Review modes for a report review."""
+
+    REVIEW_REQUIRED = "RR"
+    ALREADY_REVIEWED_OFFLINE = "AR"
+    REVIEW_NOT_REQUIRED = "RN"
+
+
+class _BaseReview(_BaseCommand):
+    """A base class for review commands."""
+
+    class Meta:
+        abstract = True
+        model = None
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Validate that concrete review commands have a unique key and model."""
+        super().__init_subclass__(**kwargs)
+
+        if not hasattr(cls.Meta, "model") or cls.Meta.model is None:
+            raise ImproperlyConfigured(f"Review command {cls.__name__!r} must specify Meta.model.")
+
+    report_ids: list[str | UUID] | None = None
+    message_to_patient: str | None = None
+    communication_method: ReportReviewCommunicationMethod | None = None
+    linked_items_urns: list[str] | None = None
+    comment: str | None = None
+
+    def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
+        errors = super()._get_error_details(method)
+
+        if self.report_ids:
+            for report_id in self.report_ids:
+                can_be_reviewed = self.Meta.model.objects.filter(  # type: ignore[attr-defined]
+                    Q(id=report_id),
+                    Q(review_mode=ReviewMode.REVIEW_REQUIRED),
+                    (Q(review__committer__isnull=True) | Q(review__entered_in_error__isnull=False)),
+                ).exists()
+                if not can_be_reviewed:
+                    errors.append(
+                        self._create_error_detail(
+                            "value",
+                            f"{self.Meta.model.__class__.__name__} with ID {report_id} cannot be reviewed.",
+                            self.report_ids,
+                        )
+                    )
+
+        return errors
+
+
+__exports__ = ()

canvas_sdk/commands/commands/review/imaging.py

@@ -0,0 +1,13 @@
+from canvas_sdk.commands.commands.review.base import _BaseReview
+from canvas_sdk.v1.data import ImagingReport
+
+
+class ImagingReviewCommand(_BaseReview):
+    """A class for managing an Imaging Review command within a specific note."""
+
+    class Meta:
+        key = "imagingReview"
+        model = ImagingReport
+
+
+__exports__ = ("ImagingReviewCommand",)

canvas_sdk/commands/commands/review/lab.py

@@ -0,0 +1,13 @@
+from canvas_sdk.commands.commands.review.base import _BaseReview
+from canvas_sdk.v1.data import LabReport
+
+
+class LabReviewCommand(_BaseReview):
+    """A class for managing a Lab Review command within a specific note."""
+
+    class Meta:
+        key = "labReview"
+        model = LabReport
+
+
+__exports__ = ("LabReviewCommand",)

canvas_sdk/commands/commands/review/referral.py

@@ -0,0 +1,13 @@
+from canvas_sdk.commands.commands.review.base import _BaseReview
+from canvas_sdk.v1.data import ReferralReport
+
+
+class ReferralReviewCommand(_BaseReview):
+    """A class for managing a Referral Review command within a specific note."""
+
+    class Meta:
+        key = "referralReview"
+        model = ReferralReport
+
+
+__exports__ = ("ReferralReviewCommand",)

canvas_sdk/commands/commands/review/uncategorized_document.py

@@ -0,0 +1,13 @@
+from canvas_sdk.commands.commands.review.base import _BaseReview
+from canvas_sdk.v1.data import UncategorizedClinicalDocument
+
+
+class UncategorizedDocumentReviewCommand(_BaseReview):
+    """A class for managing an Uncategorized Document Review command within a specific note."""
+
+    class Meta:
+        key = "uncategorizedDocumentReview"
+        model = UncategorizedClinicalDocument
+
+
+__exports__ = ("UncategorizedDocumentReviewCommand",)

canvas_sdk/commands/validation.py

@@ -0,0 +1,43 @@
+from canvas_sdk.effects import EffectType
+from canvas_sdk.effects.validation.base import (
+    ValidationError,
+    _BaseValidationErrorEffect,
+)
+
+
+class CommandValidationErrorEffect(_BaseValidationErrorEffect):
+    """
+    Effect to represent command validation errors.
+
+    This effect allows plugins to return validation errors for commands,
+    which will be displayed to users in the Canvas UI.
+
+    Example:
+        # Add validation errors
+        effect = CommandValidationErrorEffect()
+        effect.add_error("Narrative is required")
+        effect.add_error("Dosage must be a positive number")
+        return [effect.apply()]
+
+        # Or initialize with errors
+        errors = [
+            ValidationError("Narrative is required"),
+            ValidationError("This command cannot be submitted yet")
+        ]
+        effect = CommandValidationErrorEffect(errors=errors)
+        return [effect.apply()]
+
+        # Method chaining
+        effect = CommandValidationErrorEffect()
+        effect.add_error("Error 1").add_error("Error 2")
+        return [effect.apply()]
+    """
+
+    class Meta:
+        effect_type = EffectType.COMMAND_VALIDATION_ERRORS
+
+
+__all__ = __exports__ = (
+    "CommandValidationErrorEffect",
+    "ValidationError",
+)

canvas_sdk/effects/batch_originate.py

@@ -0,0 +1,22 @@
+from typing import Any
+
+from pydantic import Field
+
+from canvas_sdk.effects import EffectType, _BaseEffect
+
+
+class BatchOriginateCommandEffect(_BaseEffect):
+    """An Effect that will originate multiple commands in a batch operation."""
+
+    class Meta:
+        effect_type = EffectType.BATCH_ORIGINATE_COMMANDS
+
+    commands: list = Field(min_length=1)
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """The BatchOriginateCommandEffect's values."""
+        return {"commands": [command._origination_payload_for_batch() for command in self.commands]}
+
+
+__exports__ = ("BatchOriginateCommandEffect",)

canvas_sdk/effects/calendar/__init__.py

@@ -1,4 +1,14 @@
-from canvas_sdk.effects.calendar.create_calendar import CalendarType, CreateCalendar
-from canvas_sdk.effects.calendar.create_event import CreateEvent, EventRecurrence
+from canvas_sdk.effects.calendar.calendar import Calendar, CalendarType
+from canvas_sdk.effects.calendar.event import (
+    DaysOfWeek,
+    Event,
+    EventRecurrence,
+)
 
-__all__ = __exports__ = ("CreateCalendar", "CalendarType", "CreateEvent", "EventRecurrence")
+__all__ = __exports__ = (
+    "Calendar",
+    "CalendarType",
+    "Event",
+    "EventRecurrence",
+    "DaysOfWeek",
+)

canvas_sdk/effects/calendar/{create_calendar.py → calendar.py}

@@ -1,7 +1,9 @@
+import json
 from enum import StrEnum
 from typing import Any
 from uuid import UUID
 
+from canvas_generated.messages.effects_pb2 import Effect
 from canvas_sdk.effects import EffectType, _BaseEffect
 
 
@@ -12,15 +14,13 @@ class CalendarType(StrEnum):
     Administrative = "Admin"
 
 
-class CreateCalendar(_BaseEffect):
+class Calendar(_BaseEffect):
     """Effect to create a Calendar."""
 
-    class Meta:
-        effect_type = EffectType.CALENDAR__CREATE
-
     id: str | UUID | None = None
     provider: str | UUID
     type: CalendarType
+    location: str | UUID | None = None
     description: str | None = None
 
     @property
@@ -30,11 +30,25 @@ class CreateCalendar(_BaseEffect):
             "id": self.id,
             "provider": self.provider,
             "type": self.type,
+            "location": self.location,
             "description": self.description,
         }
 
+    def create(self) -> Effect:
+        """Send a CREATE effect for the calendar."""
+        self._validate_before_effect("create")
+
+        return Effect(
+            type=EffectType.CALENDAR__CREATE,
+            payload=json.dumps(
+                {
+                    "data": self.values,
+                }
+            ),
+        )
+
 
 __exports__ = (
-    "CreateCalendar",
+    "Calendar",
     "CalendarType",
 )

canvas_sdk/effects/calendar/event.py

@@ -0,0 +1,172 @@
+import json
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+from uuid import UUID
+
+from pydantic_core import InitErrorDetails
+
+from canvas_generated.messages.effects_pb2 import Effect
+from canvas_sdk.effects import EffectType, _BaseEffect
+
+
+class EventRecurrence(StrEnum):
+    """Calendar event recurrence."""
+
+    Daily = "DAILY"
+    Weekly = "WEEKLY"
+
+
+class DaysOfWeek(StrEnum):
+    """Days of the week."""
+
+    Monday = "MO"
+    Tuesday = "TU"
+    Wednesday = "WE"
+    Thursday = "TH"
+    Friday = "FR"
+    Saturday = "SA"
+    Sunday = "SU"
+
+
+def get_recurrence_string(
+    frequency: EventRecurrence | None, interval: int | None, days_of_week: list[DaysOfWeek] | None
+) -> str:
+    """Generate the recurrence string for an event."""
+    parts = [
+        f"FREQ={frequency}" if frequency else "",
+        f"INTERVAL={interval}" if interval else "",
+        f"BYDAY={','.join(list(map(str, days_of_week)))}" if days_of_week else "",
+    ]
+
+    return ";".join(filter(bool, parts))
+
+
+class Event(_BaseEffect):
+    """Effect to create a Calendar event."""
+
+    calendar_id: str | UUID | None = None
+    event_id: str | UUID | None = None
+    title: str | None = None
+    starts_at: datetime | None = None
+    ends_at: datetime | None = None
+    recurrence_frequency: EventRecurrence | None = None
+    recurrence_interval: int | None = None
+    recurrence_days: list[DaysOfWeek] | None = None
+    recurrence_ends_at: datetime | None = None
+    allowed_note_types: list[str] | None = None
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """The event's values."""
+        return {
+            "event_id": self.event_id,
+            "calendar_id": self.calendar_id,
+            "title": self.title,
+            "starts_at": self.starts_at.isoformat() if self.starts_at else None,
+            "ends_at": self.ends_at.isoformat() if self.ends_at else None,
+            "recurrence": get_recurrence_string(
+                self.recurrence_frequency, self.recurrence_interval, self.recurrence_days
+            ),
+            "recurrence_ends_at": self.recurrence_ends_at.isoformat()
+            if self.recurrence_ends_at
+            else None,
+            "allowed_note_types": self.allowed_note_types,
+        }
+
+    def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
+        errors = super()._get_error_details(method)
+
+        # calendar_id is required for create
+        if method == "create" and not self.calendar_id:
+            errors.append(
+                self._create_error_detail(
+                    "missing",
+                    "Field 'calendar_id' is required to create an event.",
+                    None,
+                )
+            )
+
+        if method in ("update", "delete") and not self.event_id:
+            errors.append(
+                self._create_error_detail(
+                    "missing",
+                    f"Field 'event_id' is required to {method} an event.",
+                    None,
+                )
+            )
+
+        if method in (
+            "create",
+            "update",
+        ):
+            if not self.title:
+                errors.append(
+                    self._create_error_detail(
+                        "missing",
+                        f"Field 'title' is required to {method} an event.",
+                        None,
+                    )
+                )
+
+            if not self.starts_at:
+                errors.append(
+                    self._create_error_detail(
+                        "missing",
+                        f"Field 'starts_at' is required to {method} an event.",
+                        None,
+                    )
+                )
+
+            if not self.ends_at:
+                errors.append(
+                    self._create_error_detail(
+                        "missing",
+                        f"Field 'ends_at' is required to {method} an event.",
+                        None,
+                    )
+                )
+
+        return errors
+
+    def create(self) -> Effect:
+        """Send a CREATE effect for the calendar event."""
+        self._validate_before_effect("create")
+
+        return Effect(
+            type=EffectType.CALENDAR__EVENT__CREATE,
+            payload=json.dumps(
+                {
+                    "data": self.values,
+                }
+            ),
+        )
+
+    def update(self) -> Effect:
+        """Send an UPDATE effect for the calendar event."""
+        self._validate_before_effect("update")
+
+        return Effect(
+            type=EffectType.CALENDAR__EVENT__UPDATE,
+            payload=json.dumps(
+                {
+                    "data": self.values,
+                }
+            ),
+        )
+
+    def delete(self) -> Effect:
+        """Send a DELETE effect for the calendar event."""
+        self._validate_before_effect("delete")
+
+        return Effect(
+            type=EffectType.CALENDAR__EVENT__DELETE,
+            payload=json.dumps(
+                {
+                    "data": self.values,
+                }
+            ),
+        )
+
+
+__exports__ = ("Event", "EventRecurrence", "DaysOfWeek")

canvas_sdk/effects/claim_label.py

@@ -0,0 +1,93 @@
+from dataclasses import dataclass
+from typing import Any
+from uuid import UUID
+
+from pydantic import conlist
+from pydantic_core import InitErrorDetails
+
+from canvas_sdk.effects.base import EffectType, _BaseEffect
+from canvas_sdk.v1.data import Claim
+from canvas_sdk.v1.data.common import ColorEnum
+
+
+@dataclass
+class Label:
+    """A class representing a label."""
+
+    color: ColorEnum
+    name: str
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the label to a dictionary."""
+        return {"color": self.color.value, "name": self.name}
+
+
+class _ClaimLabelBase(_BaseEffect):
+    """Base class for managing ClaimLabels."""
+
+    claim_id: UUID | str
+    labels: conlist(str | Label, min_length=1)  # type: ignore
+
+    def _check_if_claim_exists(self) -> list[InitErrorDetails]:
+        if Claim.objects.filter(id=self.claim_id).exists():
+            return []
+        return [
+            (
+                self._create_error_detail(
+                    "value",
+                    f"Claim with id {self.claim_id} does not exist.",
+                    self.claim_id,
+                )
+            )
+        ]
+
+    def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
+        errors = super()._get_error_details(method)
+        if not Claim.objects.filter(id=self.claim_id).exists():
+            errors.append(
+                self._create_error_detail(
+                    "value",
+                    f"Claim with id {self.claim_id} does not exist.",
+                    self.claim_id,
+                )
+            )
+        return errors
+
+
+class AddClaimLabel(_ClaimLabelBase):
+    """Effect to add a label to a Claim."""
+
+    class Meta:
+        effect_type = EffectType.ADD_CLAIM_LABEL
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """The values for adding a claim label."""
+        return {
+            "claim_id": str(self.claim_id),
+            "labels": [
+                label.to_dict() if isinstance(label, Label) else {"name": label}
+                for label in self.labels
+            ],
+        }
+
+
+class RemoveClaimLabel(_ClaimLabelBase):
+    """Effect to remove a label from a Claim."""
+
+    class Meta:
+        effect_type = EffectType.REMOVE_CLAIM_LABEL
+
+    labels: conlist(str, min_length=1)  # type: ignore
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """The values for removing a claim label."""
+        return {"claim_id": str(self.claim_id), "labels": list(self.labels)}
+
+
+__exports__ = (
+    "Label",
+    "AddClaimLabel",
+    "RemoveClaimLabel",
+)

canvas_sdk/effects/claim_line_item.py

@@ -0,0 +1,47 @@
+from typing import Any
+from uuid import UUID
+
+from pydantic_core import InitErrorDetails
+
+from canvas_sdk.effects.base import EffectType, _BaseEffect
+from canvas_sdk.v1.data import ClaimLineItem
+
+
+class UpdateClaimLineItem(_BaseEffect):
+    """
+    An Effect that updates a Claim Line Item.
+    """
+
+    class Meta:
+        effect_type = EffectType.UPDATE_CLAIM_LINE_ITEM
+
+    claim_line_item_id: str | UUID
+    charge: float | None = None
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """The values for the payload."""
+        if self.charge is None:
+            return {}
+        return {"charge": str(self.charge)}
+
+    @property
+    def effect_payload(self) -> dict[str, Any]:
+        """The payload of the effect."""
+        return {"data": self.values, "claim_line_item_id": str(self.claim_line_item_id)}
+
+    def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
+        errors = super()._get_error_details(method)
+
+        if not ClaimLineItem.objects.filter(id=self.claim_line_item_id).exists():
+            errors.append(
+                self._create_error_detail(
+                    "value",
+                    "Claim Line Item does not exist",
+                    self.claim_line_item_id,
+                )
+            )
+        return errors
+
+
+__exports__ = ("UpdateClaimLineItem",)

canvas_sdk/effects/claim_queue.py

@@ -0,0 +1,49 @@
+from typing import Any
+from uuid import UUID
+
+from pydantic import constr
+from pydantic_core import InitErrorDetails
+
+from canvas_sdk.effects.base import EffectType, _BaseEffect
+from canvas_sdk.v1.data import Claim, ClaimQueue
+
+
+class MoveClaimToQueue(_BaseEffect):
+    """
+    An Effect that moves a Claim to a Queue.
+    """
+
+    class Meta:
+        effect_type = EffectType.MOVE_CLAIM_TO_QUEUE
+
+    claim_id: UUID | str
+    queue: constr(min_length=1, strip_whitespace=True)  # type: ignore[valid-type]
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """The claim_id and queue_id."""
+        return {"claim_id": str(self.claim_id), "queue": self.queue}
+
+    def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
+        errors = super()._get_error_details(method)
+
+        if not Claim.objects.filter(id=self.claim_id).exists():
+            errors.append(
+                self._create_error_detail(
+                    "value",
+                    "Claim does not exist",
+                    self.claim_id,
+                )
+            )
+        if not ClaimQueue.objects.filter(name=self.queue).exists():
+            errors.append(
+                self._create_error_detail(
+                    "value",
+                    "Queue does not exist",
+                    self.queue,
+                )
+            )
+        return errors
+
+
+__exports__ = ("MoveClaimToQueue",)

canvas_sdk/effects/fax/__init__.py

@@ -0,0 +1,3 @@
+from canvas_sdk.effects.fax.note import FaxNoteEffect
+
+__all__ = __exports__ = ("FaxNoteEffect",)