canvas 0.53.2__py3-none-any.whl → 0.54.0__py3-none-any.whl

canvas_sdk/caching/plugins.py

@@ -3,18 +3,21 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from canvas_sdk.caching.client import get_cache as get_cache_client
-from canvas_sdk.utils.plugins import plugin_only
+from canvas_sdk.utils.plugins import plugin_context
 from settings import CANVAS_SDK_CACHE_TIMEOUT_SECONDS
 
 if TYPE_CHECKING:
     from canvas_sdk.caching.base import Cache
 
 
-@plugin_only
+@plugin_context
 def get_cache(**kwargs: Any) -> Cache:
     """Get the cache client for plugins."""
-    prefix = kwargs["plugin_name"]
-    return get_cache_client("plugins", prefix, CANVAS_SDK_CACHE_TIMEOUT_SECONDS)
+    return get_cache_client(
+        driver="plugins",
+        prefix=kwargs["plugin_name"],
+        max_timeout_seconds=CANVAS_SDK_CACHE_TIMEOUT_SECONDS,
+    )
 
 
 __exports__ = ("get_cache",)

canvas_sdk/effects/payment_processor.py

@@ -0,0 +1,137 @@
+from enum import StrEnum
+from typing import Any
+
+from canvas_sdk.effects import EffectType, _BaseEffect
+
+
+class PaymentProcessorMetadata(_BaseEffect):
+    """PaymentProcessorInfo effect class."""
+
+    class Meta:
+        effect_type = EffectType.REVENUE__PAYMENT_PROCESSOR__METADATA
+
+    class PaymentProcessorType(StrEnum):
+        """Enum for payment processor types."""
+
+        CARD = "card"
+
+    identifier: str
+    type: PaymentProcessorType
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """Return the values of the PaymentProcessorMetadata."""
+        return {
+            "identifier": self.identifier,
+            "type": self.type.value,
+        }
+
+
+class PaymentProcessorForm(_BaseEffect):
+    """PaymentProcessorForm effect class."""
+
+    class Meta:
+        effect_type = EffectType.REVENUE__PAYMENT_PROCESSOR__FORM
+
+    intent: str
+    content: str
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """Return the values of the PaymentProcessorMetadata."""
+        return {
+            "intent": self.intent,
+            "content": self.content,
+        }
+
+
+class CardTransaction(_BaseEffect):
+    """CardTransaction effect class."""
+
+    class Meta:
+        effect_type = EffectType.REVENUE__PAYMENT_PROCESSOR__CREDIT_CARD_TRANSACTION
+
+    success: bool
+    transaction_id: str | None
+    error_code: str | None = None
+    api_response: dict
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """Return the values of the CreditCardTransaction."""
+        return {
+            "success": self.success,
+            "transaction_id": self.transaction_id,
+            "api_response": self.api_response,
+            "error_code": self.error_code,
+        }
+
+
+class PaymentMethod(_BaseEffect):
+    """PaymentMethod effect class."""
+
+    class Meta:
+        effect_type = EffectType.REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHOD
+
+    payment_method_id: str
+    card_holder_name: str | None
+    brand: str
+    postal_code: str | None = None
+    country: str | None = None
+    expiration_year: int
+    expiration_month: int
+    card_last_four_digits: str
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """Return the values of the PaymentMethod."""
+        return {
+            "payment_method_id": self.payment_method_id,
+            "card_holder_name": self.card_holder_name,
+            "brand": self.brand,
+            "postal_code": self.postal_code,
+            "country": self.country,
+            "expiration_year": self.expiration_year,
+            "expiration_month": self.expiration_month,
+            "card_last_four_digits": self.card_last_four_digits,
+        }
+
+
+class AddPaymentMethodResponse(_BaseEffect):
+    """AddPaymentMethodResponse effect class."""
+
+    class Meta:
+        effect_type = EffectType.REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHOD__ADD_RESPONSE
+
+    success: bool
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """Return the values of the AddPaymentMethodResponse."""
+        return {"success": self.success}
+
+
+class RemovePaymentMethodResponse(_BaseEffect):
+    """RemovePaymentMethodResponse effect class."""
+
+    class Meta:
+        effect_type = EffectType.REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHOD__REMOVE_RESPONSE
+
+    success: bool
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """Return the values of the RemovePaymentMethodResponse."""
+        return {
+            "success": self.success,
+        }
+
+
+__exports__ = (
+    "PaymentProcessorMetadata",
+    "PaymentProcessorForm",
+    "CardTransaction",
+    "PaymentMethod",
+    "AddPaymentMethodResponse",
+    "RemovePaymentMethodResponse",
+)

canvas_sdk/handlers/payment_processors/__init__.py

@@ -0,0 +1 @@
+__exports__ = ()

canvas_sdk/handlers/payment_processors/base.py

@@ -0,0 +1,93 @@
+import base64
+from abc import ABC
+
+from canvas_sdk.effects import Effect
+from canvas_sdk.effects.payment_processor import PaymentProcessorMetadata
+from canvas_sdk.events import EventType
+from canvas_sdk.handlers import BaseHandler
+
+
+class PaymentProcessor(BaseHandler, ABC):
+    """
+    Abstract Base class for payment processors.
+    """
+
+    RESPONDS_TO = [
+        EventType.Name(EventType.REVENUE__PAYMENT_PROCESSOR__LIST),
+        EventType.Name(EventType.REVENUE__PAYMENT_PROCESSOR__SELECTED),
+        EventType.Name(EventType.REVENUE__PAYMENT_PROCESSOR__CHARGE),
+        EventType.Name(EventType.REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__LIST),
+        EventType.Name(EventType.REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__ADD),
+        EventType.Name(EventType.REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__REMOVE),
+    ]
+
+    TYPE: PaymentProcessorMetadata.PaymentProcessorType
+
+    @property
+    def identifier(self) -> str:
+        """The application identifier."""
+        identifier = f"{self.__class__.__module__}:{self.__class__.__qualname__}"
+
+        return base64.b64encode(identifier.encode("utf-8")).decode("utf-8")
+
+    def compute(self) -> list[Effect]:
+        """Compute the effects to be applied."""
+        if self.event.type == EventType.REVENUE__PAYMENT_PROCESSOR__LIST and (
+            "payment_type" not in self.event.context
+            or self.event.context["payment_type"] == self.TYPE
+        ):
+            return [self.metadata().apply()]
+        elif self.event.type == EventType.REVENUE__PAYMENT_PROCESSOR__SELECTED:
+            effects = self._on_payment_processor_selected()
+            return effects
+        elif self.event.type == EventType.REVENUE__PAYMENT_PROCESSOR__CHARGE:
+            effect = self._charge()
+            return [effect] if effect else []
+        elif self.event.type == EventType.REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__LIST:
+            # This event is used to list payment methods, which may not be applicable for all processors.
+            # Subclasses should override this method if they support listing payment methods.
+            return self._payment_methods()
+        elif self.event.type == EventType.REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__ADD:
+            effect = self._add_payment_method()
+            return [effect] if effect else []
+        elif self.event.type == EventType.REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__REMOVE:
+            effect = self._remove_payment_method()
+            return [effect] if effect else []
+
+        return []
+
+    def metadata(self) -> PaymentProcessorMetadata:
+        """Return information about the payment processor."""
+        return PaymentProcessorMetadata(identifier=self.identifier, type=self.TYPE)
+
+    def _on_payment_processor_selected(self) -> list[Effect]:
+        """Handle the event when a payment processor is selected."""
+        # This method should be overridden by subclasses to handle specific logic
+        # when a payment processor is selected.
+        return []
+
+    def _charge(self) -> Effect | None:
+        """Handle the event when a charge is made."""
+        # This method should be overridden by subclasses to handle specific logic
+        # when a charge is made.
+        return None
+
+    def _payment_methods(self) -> list[Effect]:
+        """List payment methods for the processor."""
+        # This method should be overridden by subclasses if they support listing payment methods.
+        return []
+
+    def _add_payment_method(self) -> Effect | None:
+        """Handle the event when a payment method is added."""
+        # This method should be overridden by subclasses to handle specific logic
+        # when a payment method is added.
+        return None
+
+    def _remove_payment_method(self) -> Effect | None:
+        """Handle the event when a payment method is removed."""
+        # This method should be overridden by subclasses to handle specific logic
+        # when a payment method is removed.
+        return None
+
+
+__exports__ = ("PaymentProcessor",)

canvas_sdk/handlers/payment_processors/card.py

@@ -0,0 +1,200 @@
+from abc import ABC, abstractmethod
+from decimal import Decimal
+from enum import StrEnum
+
+from canvas_sdk.effects import Effect
+from canvas_sdk.effects.payment_processor import (
+    AddPaymentMethodResponse,
+    CardTransaction,
+    PaymentMethod,
+    PaymentProcessorForm,
+    PaymentProcessorMetadata,
+    RemovePaymentMethodResponse,
+)
+from canvas_sdk.handlers.payment_processors.base import PaymentProcessor
+from canvas_sdk.v1.data import Patient
+
+
+class CardPaymentProcessor(PaymentProcessor, ABC):
+    """Base Card Payment Processor Handler."""
+
+    TYPE = PaymentProcessorMetadata.PaymentProcessorType.CARD
+
+    class PaymentIntent(StrEnum):
+        """Enum for payment actions."""
+
+        ADD_CARD = "add_card"
+        PAY = "pay"
+
+    def _on_payment_processor_selected(self) -> list[Effect]:
+        """Handle the event when a payment processor is selected."""
+        if self.event.context.get("identifier") == self.identifier:
+            intent = self.event.context.get("intent")
+            effects = self.on_payment_processor_selected(intent=intent)
+            return [effect.apply() for effect in effects]
+
+        return []
+
+    def _charge(self) -> Effect | None:
+        """Handle the event when a charge is made."""
+        if self.event.context.get("identifier") == self.identifier:
+            patient = (
+                Patient.objects.get(id=self.event.context.get("patient", {}).get("id"))
+                if self.event.context.get("patient")
+                else None
+            )
+
+            amount = Decimal(str(self.event.context.get("amount")))
+            token = str(self.event.context.get("token"))
+            effect = self.charge(amount=amount, token=token, patient=patient)
+
+            return effect.apply() if effect else None
+
+        return None
+
+    def _payment_methods(self) -> list[Effect]:
+        """List payment methods for the card payment processor."""
+        if self.event.context.get("identifier") == self.identifier:
+            patient = (
+                Patient.objects.get(id=self.event.context.get("patient", {}).get("id"))
+                if self.event.context.get("patient")
+                else None
+            )
+            effects = self.payment_methods(patient=patient)
+            return [effect.apply() for effect in effects]
+
+        return []
+
+    def _add_payment_method(self) -> Effect | None:
+        """Handle the event when a card is added."""
+        if self.event.context.get("identifier") == self.identifier:
+            patient = (
+                Patient.objects.get(id=self.event.context.get("patient", {}).get("id"))
+                if self.event.context.get("patient")
+                else None
+            )
+
+            if not patient:
+                return None
+
+            token = str(self.event.context.get("token"))
+            effect = self.add_payment_method(token=token, patient=patient)
+            return effect.apply() if effect else None
+
+        return None
+
+    def _remove_payment_method(self) -> Effect | None:
+        """Handle the event when a payment method is removed."""
+        if self.event.context.get("identifier") == self.identifier:
+            patient = (
+                Patient.objects.get(id=self.event.context.get("patient", {}).get("id"))
+                if self.event.context.get("patient")
+                else None
+            )
+
+            if not patient:
+                return None
+
+            token = str(self.event.context.get("token"))
+            effect = self.remove_payment_method(token=token, patient=patient)
+            return effect.apply() if effect else None
+
+        return None
+
+    def on_payment_processor_selected(self, intent: str | None) -> list[PaymentProcessorForm]:
+        """Handle the event when a payment processor is selected."""
+        patient = (
+            Patient.objects.get(id=self.event.context.get("patient", {}).get("id"))
+            if self.event.context.get("patient")
+            else None
+        )
+        match intent:
+            case self.PaymentIntent.ADD_CARD:
+                return [self.add_card_form(patient)]
+            case self.PaymentIntent.PAY:
+                return [self.payment_form(patient)]
+            case None:
+                return [self.payment_form(patient), self.add_card_form(patient)]
+            case _:
+                return []
+
+    @abstractmethod
+    def payment_form(self, patient: Patient | None = None) -> PaymentProcessorForm:
+        """Return the payment form for the credit card processor.
+
+        Args:
+            patient (Patient | None): The patient for whom the payment is being processed.
+
+        Returns:
+            PaymentProcessorForm: The form for processing the payment.
+        """
+        raise NotImplementedError("Subclasses must implement the payment_form method.")
+
+    @abstractmethod
+    def add_card_form(self, patient: Patient | None = None) -> PaymentProcessorForm:
+        """Return the form for adding a card.
+
+        Args:
+            patient (Patient | None): The patient for whom the add is being added.
+
+        Returns:
+            PaymentProcessorForm: The form for adding a card.
+        """
+        raise NotImplementedError("Subclasses must implement the add_card_form method.")
+
+    @abstractmethod
+    def charge(
+        self, amount: Decimal, token: str, patient: Patient | None = None
+    ) -> CardTransaction:
+        """Charge a credit/debit card using the provided token.
+
+        Args:
+            amount (Decimal): The amount to charge.
+            token (str): The token representing the credit card.
+            patient (Patient | None): The patient for whom the charge is being made.
+
+        Returns:
+            CardTransaction: The result of the card transaction.
+        """
+        raise NotImplementedError("Subclasses must implement the charge method.")
+
+    @abstractmethod
+    def payment_methods(self, patient: Patient | None = None) -> list[PaymentMethod]:
+        """List payment methods for the card payment processor.
+
+        Args:
+            patient (Patient | None): The patient for whom the payment methods are being listed.
+
+        Returns:
+            list[PaymentMethod]: A list of payment methods available for the card payment processor.
+        """
+        raise NotImplementedError("Subclasses must implement the payment_methods method.")
+
+    @abstractmethod
+    def add_payment_method(self, token: str, patient: Patient) -> AddPaymentMethodResponse:
+        """Add a payment method for the card payment processor.
+
+        Args:
+            token (str): The token representing the payment method.
+            patient (Patient): The patient for whom the payment method is being added.
+
+        Returns:
+            AddPaymentMethodResponse: The response indicating the result of the addition operation.
+        """
+        raise NotImplementedError("Subclasses must implement the add_payment_method method.")
+
+    @abstractmethod
+    def remove_payment_method(self, token: str, patient: Patient) -> RemovePaymentMethodResponse:
+        """Remove a payment method for the card payment processor.
+
+        Args:
+            token (str): The token representing the payment method to be removed.
+            patient (Patient): The patient for whom the payment method is being removed.
+
+        Returns:
+            RemovePaymentMethodResponse: The response indicating the result of the removal operation.
+        """
+        raise NotImplementedError("Subclasses must implement the remove_payment_method method.")
+
+
+__exports__ = ("CardPaymentProcessor",)

canvas_sdk/questionnaires/utils.py

@@ -7,7 +7,7 @@ from typing import Any, TypedDict
 import yaml
 from jsonschema import Draft7Validator, validators
 
-from canvas_sdk.utils.plugins import plugin_only
+from canvas_sdk.utils.plugins import plugin_context
 
 
 class Response(TypedDict):
@@ -75,7 +75,7 @@ def extend_with_defaults(validator_class: type[Draft7Validator]) -> type[Draft7V
 ExtendedDraft7Validator = extend_with_defaults(Draft7Validator)
 
 
-@plugin_only
+@plugin_context
 def from_yaml(questionnaire_name: str, **kwargs: Any) -> QuestionnaireConfig | None:
     """Load a Questionnaire configuration from a YAML file.
 

canvas_sdk/templates/utils.py

@@ -3,12 +3,14 @@ from typing import Any
 
 from django.template import Context, Template
 
-from canvas_sdk.utils.plugins import plugin_only
+from canvas_sdk.utils.plugins import plugin_context
 
 
-@plugin_only
+@plugin_context
 def render_to_string(
-    template_name: str, context: dict[str, Any] | None = None, **kwargs: Any
+    template_name: str,
+    context: dict[str, Any] | None = None,
+    **kwargs: Any,
 ) -> str | None:
     """Load a template and render it with the given context.
 

canvas_sdk/utils/plugins.py

@@ -8,19 +8,39 @@ from canvas_sdk.utils.metrics import measured
 from settings import PLUGIN_DIRECTORY
 
 
+def find_plugin_ancestor(frame: FrameType | None, max_depth: int = 10) -> FrameType | None:
+    """
+    Recurse backwards to find any plugin ancestor of this frame.
+    """
+    parent_frame = frame.f_back if frame else None
+
+    if not parent_frame:
+        return None
+
+    if max_depth == 0:
+        return None
+
+    if "__is_plugin__" in parent_frame.f_globals:
+        return parent_frame
+
+    return find_plugin_ancestor(frame=parent_frame, max_depth=max_depth - 1)
+
+
 @measured
-def plugin_only(func: Callable[..., Any]) -> Callable[..., Any]:
+def plugin_context(func: Callable[..., Any]) -> Callable[..., Any]:
     """Decorator to restrict a function's execution to plugins only."""
 
     def wrapper(*args: Any, **kwargs: Any) -> Any:
-        current_frame = inspect.currentframe()
-        caller = current_frame.f_back if current_frame else None
+        plugin_frame = find_plugin_ancestor(inspect.currentframe())
 
-        if not caller or "__is_plugin__" not in caller.f_globals:
-            return None
+        if not plugin_frame:
+            raise RuntimeError(
+                "Method that expected plugin context was called from outside a plugin."
+            )
 
-        plugin_name = caller.f_globals["__name__"].split(".")[0]
+        plugin_name = plugin_frame.f_globals["__name__"].split(".")[0]
         plugin_dir = Path(PLUGIN_DIRECTORY) / plugin_name
+
         kwargs["plugin_name"] = plugin_name
         kwargs["plugin_dir"] = plugin_dir.resolve()
 
@@ -30,24 +50,17 @@ def plugin_only(func: Callable[..., Any]) -> Callable[..., Any]:
 
 
 @measured
-def is_plugin_caller(depth: int = 10, frame: FrameType | None = None) -> tuple[bool, str | None]:
+def is_plugin_caller() -> tuple[bool, str | None]:
     """Check if a function is called from a plugin."""
-    current_frame = frame or inspect.currentframe()
-    caller = current_frame.f_back if current_frame else None
-
-    if not caller:
-        return False, None
+    plugin_frame = find_plugin_ancestor(inspect.currentframe())
 
-    if "__is_plugin__" not in caller.f_globals:
-        if depth > 0:
-            return is_plugin_caller(frame=caller, depth=depth - 1)
-        else:
-            return False, None
+    if plugin_frame:
+        module = plugin_frame.f_globals.get("__name__")
+        qualname = plugin_frame.f_code.co_qualname
 
-    module = caller.f_globals.get("__name__")
-    qualname = caller.f_code.co_qualname
+        return True, f"{module}.{qualname}"
 
-    return True, f"{module}.{qualname}"
+    return False, None
 
 
 __exports__ = ()

canvas_sdk/v1/data/patient.py

@@ -99,6 +99,13 @@ class Patient(Model):
     def __str__(self) -> str:
         return f"{self.first_name} {self.last_name}"
 
+    @property
+    def full_name(self) -> str:
+        """Returns the patient's full name."""
+        return " ".join(
+            n for n in (self.first_name, self.middle_name, self.last_name, self.suffix) if n
+        )
+
     def age_at(self, time: arrow.Arrow) -> float:
         """Given a datetime, returns what the patient's age would be at that datetime."""
         age = float(0)

plugin_runner/allowed-module-imports.json

@@ -279,6 +279,14 @@
   "canvas_sdk.effects.patient_profile_configuration": [
     "PatientProfileConfiguration"
   ],
+  "canvas_sdk.effects.payment_processor": [
+    "AddPaymentMethodResponse",
+    "CardTransaction",
+    "PaymentMethod",
+    "PaymentProcessorForm",
+    "PaymentProcessorMetadata",
+    "RemovePaymentMethodResponse"
+  ],
   "canvas_sdk.effects.protocol_card": [
     "ProtocolCard",
     "Recommendation"
@@ -364,6 +372,12 @@
   "canvas_sdk.handlers.cron_task": [
     "CronTask"
   ],
+  "canvas_sdk.handlers.payment_processors.base": [
+    "PaymentProcessor"
+  ],
+  "canvas_sdk.handlers.payment_processors.card": [
+    "CardPaymentProcessor"
+  ],
   "canvas_sdk.handlers.simple_api": [
     "APIKeyAuthMixin",
     "APIKeyCredentials",

plugin_runner/installation.py

@@ -147,6 +147,8 @@ def download_plugin(plugin_package: str) -> Generator[Path, None, None]:
 
         with open(download_path, "wb") as download_file:
             response = requests.request(method=method, url=f"https://{host}{path}", headers=headers)
+            response.raise_for_status()
+
             download_file.write(response.content)
 
         yield download_path
@@ -168,7 +170,8 @@ def install_plugin(plugin_name: str, attributes: PluginAttributes) -> None:
 
         install_plugin_secrets(plugin_name=plugin_name, secrets=attributes["secrets"])
     except Exception as e:
-        log.error(f'Failed to install plugin "{plugin_name}", version {attributes["version"]}')
+        log.error(f'Failed to install plugin "{plugin_name}", version {attributes["version"]}: {e}')
+
         sentry_sdk.capture_exception(e)
 
         raise PluginInstallationError() from e

plugin_runner/plugin_runner.py

@@ -1,3 +1,4 @@
+import base64
 import json
 import os
 import pathlib
@@ -213,6 +214,28 @@ class PluginRunner(PluginRunnerServicer):
                 # respond to SimpleAPI request events are not relevant
                 plugin_name = event.context["plugin_name"]
                 relevant_plugins = [p for p in relevant_plugins if p.startswith(f"{plugin_name}:")]
+            elif event_type in {
+                EventType.REVENUE__PAYMENT_PROCESSOR__CHARGE,
+                EventType.REVENUE__PAYMENT_PROCESSOR__SELECTED,
+                EventType.REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__LIST,
+                EventType.REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__ADD,
+                EventType.REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__REMOVE,
+            }:
+                # The target plugin's name will be part of the payment processor identifier, so other plugins that
+                # respond to payment processor charge events are not relevant
+                try:
+                    plugin_name = (
+                        base64.b64decode(event.context["identifier"]).decode("utf-8").split(".")[0]
+                    )
+                    relevant_plugins = [
+                        p for p in relevant_plugins if p.startswith(f"{plugin_name}:")
+                    ]
+                except Exception as ex:
+                    log.error(
+                        f"Failed to decode identifier for event {event_name} with context {event.context}"
+                    )
+                    sentry_sdk.capture_exception(ex)
+                    relevant_plugins = []
 
             effect_list = []
 

plugin_runner/sandbox.py

@@ -225,6 +225,7 @@ THIRD_PARTY_MODULES = {
     },
     "pydantic": {
         "BaseModel",
+        "ConfigDict",
         "conint",
         "constr",
         "Field",