mphapi 0.5.0__py3-none-any.whl → 1.11.0__py3-none-any.whl

mphapi/credentials.py

@@ -0,0 +1,256 @@
+import getpass
+import json
+import os
+import time
+from pathlib import Path
+
+import requests
+from pydantic import BaseModel, Field, RootModel
+
+from .fields import camel_case_model_config
+
+
+class RawCredentials(BaseModel):
+    model_config = camel_case_model_config
+
+    email: str
+    id_token: str
+    refresh_token: str
+    expires_at: float
+
+    def store(
+        self, api_key: str, referer: str, credentials_path: Path
+    ) -> "Credentials":
+        stored_credentials = StoredCredentials(
+            api_key=api_key,
+            referer=referer,
+            email=self.email,
+            id_token=self.id_token,
+            refresh_token=self.refresh_token,
+            expires_at=self.expires_at,
+        )
+
+        os.makedirs(os.path.dirname(credentials_path), exist_ok=True)
+
+        with credentials_path.open("w+") as f:
+            json.dump(
+                stored_credentials.model_dump(
+                    mode="json", by_alias=True, exclude_none=True
+                ),
+                f,
+            )
+
+        return Credentials(
+            referer=referer,
+            credentials_path=credentials_path,
+            api_key=api_key,
+            email=stored_credentials.email,
+            id_token=stored_credentials.id_token,
+            refresh_token=stored_credentials.refresh_token,
+            expires_at=stored_credentials.expires_at,
+        )
+
+
+class StoredCredentials(RawCredentials):
+    api_key: str
+    referer: str
+
+
+class Credentials(StoredCredentials):
+    credentials_path: Path = Field(..., exclude=True)
+
+    def refresh_if_needed(self) -> "Credentials | None":
+        # # There's more than 5 minutes until the credentials need refreshing. Don't bother.
+        if self.expires_at > time.time() + 5 * 60:
+            return None
+
+        new_credentials = refresh_token(self.api_key, self.referer, self.refresh_token)
+        return new_credentials.store(self.api_key, self.referer, self.credentials_path)
+
+
+class GoogleException(Exception):
+    def __init__(self, message: str):
+        self.message = message
+
+
+class GoogleError(BaseModel):
+    code: int
+    message: str
+    # errors omitted as unused
+
+
+class GoogleResponseError(BaseModel):
+    model_config = camel_case_model_config
+
+    error: GoogleError
+
+    def to_exception(self) -> GoogleException:
+        return GoogleException(self.error.message)
+
+
+class GoogleResponse[Result: BaseModel](RootModel[Result | GoogleResponseError]):
+    pass
+
+
+class SignInResult(BaseModel):
+    """
+    The result of signing in.
+    See https://docs.cloud.google.com/identity-platform/docs/reference/rest/v1/accounts/signInWithPassword
+    """
+
+    model_config = camel_case_model_config
+
+    email: str
+    """The email of the authenticated user. Always present in the response."""
+
+    id_token: str
+    """An Identity Platform ID token for the authenticated user."""
+
+    refresh_token: str
+    """An Identity Platform refresh token for the authenticated user."""
+
+    expires_in: int
+    """The number of seconds until the Identity Platform ID token expires."""
+
+
+class RefreshTokenResult(BaseModel):
+    """
+    The result of refreshing a refresh_token.
+    See https://cloud.google.com/identity-platform/docs/use-rest-api#section-refresh-token
+    """
+
+    # NOT camelCase
+
+    expires_in: int
+    """The number of seconds in which the ID token expires."""
+
+    token_type: str
+    """The type of the refresh token, always "Bearer"."""
+
+    refresh_token: str
+    """The Identity Platform refresh token provided in the request or a new refresh token."""
+
+    id_token: str
+    """An Identity Platform ID token."""
+
+    user_id: str
+    """The uid corresponding to the provided ID token."""
+
+    project_id: str
+    """Your Google Cloud project ID."""
+
+
+def get_credentials(api_key: str, referer: str) -> Credentials:
+    credentials_path = get_credentials_path()
+
+    credentials = get_stored_credentials(credentials_path)
+    if credentials is not None:
+        try:
+            credentials.refresh_if_needed()
+        except GoogleException as e:
+            # `INVALID_ID_TOKEN` means the user must login again.
+            if e.message != "INVALID_ID_TOKEN":
+                raise e
+
+        return credentials
+
+    email = input("Email: ")
+    login_credentials: RawCredentials | None = None
+
+    while True:
+        try:
+            password = getpass.getpass("Password: ")
+            login_credentials = sign_in(api_key, email, password)
+            break
+        except GoogleException as e:
+            if e.message == "INVALID_PASSWORD":
+                continue
+
+            raise e
+
+    return login_credentials.store(api_key, referer, credentials_path)
+
+
+def get_credentials_path() -> Path:
+    home = Path.home()
+    return home.joinpath(".mph", "credentials.json")
+
+
+def get_stored_credentials(credentials_path: Path) -> Credentials | None:
+    try:
+        with credentials_path.open() as f:
+            credentials_json = json.load(f)
+            stored_credentials = StoredCredentials.model_validate(credentials_json)
+    except FileNotFoundError:
+        return None
+
+    credentials = Credentials(
+        email=stored_credentials.email,
+        id_token=stored_credentials.id_token,
+        refresh_token=stored_credentials.refresh_token,
+        expires_at=stored_credentials.expires_at,
+        api_key=stored_credentials.api_key,
+        referer=stored_credentials.referer,
+        credentials_path=credentials_path,
+    )
+
+    return credentials
+
+
+def refresh_token(api_key: str, referer: str, refresh_token: str) -> RawCredentials:
+    response = requests.post(
+        "https://securetoken.googleapis.com/v1/token",
+        data={"grant_type": "refresh_token", "refresh_token": refresh_token},
+        params={
+            "key": api_key,
+        },
+        headers={
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Referer": referer,
+        },
+    )
+
+    result = (
+        GoogleResponse[RefreshTokenResult].model_validate_json(response.content).root
+    )
+
+    if isinstance(result, GoogleResponseError):
+        raise result.to_exception()
+
+    return RawCredentials(
+        email="",
+        id_token=result.id_token,
+        refresh_token=result.refresh_token,
+        expires_at=time.time() + result.expires_in,
+    )
+
+
+def sign_in(api_key: str, email: str, password: str) -> RawCredentials:
+    response = requests.post(
+        "https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword",
+        json={
+            "email": email,
+            "password": password,
+            "returnSecureToken": "true",
+        },
+        params={
+            "key": api_key,
+        },
+        headers={"Referer": "http://myprice.health"},
+    )
+
+    result = GoogleResponse[SignInResult].model_validate_json(response.content).root
+
+    if isinstance(result, GoogleResponseError):
+        raise result.to_exception()
+
+    sign_in_result = result
+
+    credentials = RawCredentials(
+        email=sign_in_result.email,
+        id_token=sign_in_result.id_token,
+        refresh_token=sign_in_result.refresh_token,
+        expires_at=time.time() + sign_in_result.expires_in,
+    )
+
+    return credentials

mphapi/date.py

@@ -1,39 +1,54 @@
-from datetime import datetime
-from typing import Any
+from abc import abstractmethod
+from datetime import datetime as dt
+from datetime import tzinfo
+from typing import Any, ClassVar, Self, SupportsIndex
 
 from pydantic import GetCoreSchemaHandler
 from pydantic_core import CoreSchema, core_schema
 
 
-class Date:
-    """Date is a custom type for representing dates in the format YYYYMMDD"""
-
-    year: int
-    month: int
-    day: int
+class AbstractDateTime:
+    format: ClassVar[str]
+    secondary_formats: ClassVar[list[str]] = []
+    datetime: dt
 
-    def __init__(self, year: int, month: int, day: int):
-        self.year = year
-        self.month = month
-        self.day = day
+    @classmethod
+    @abstractmethod
+    def from_datetime(cls, datetime: dt) -> Self:
+        pass
 
     def __str__(self):
-        return f"{self.year}{self.month:02d}{self.day:02d}"
+        return self.datetime.strftime(self.format)
 
     # Based off of this: https://docs.pydantic.dev/2.1/usage/types/custom/#handling-third-party-types
     @classmethod
     def __get_pydantic_core_schema__(
         cls, source_type: Any, handler: GetCoreSchemaHandler
     ) -> CoreSchema:
-        def to_date(value: str) -> Date:
-            time = datetime.strptime(value, "%Y%m%d")
+        def to_datetime_cls(value: str) -> Self:
+            datetime: dt | None = None
+
+            if len(cls.secondary_formats) == 0:
+                datetime = dt.strptime(value, cls.format)
+            else:
+                formats = [cls.format, *cls.secondary_formats]
+                for format in formats:
+                    try:
+                        datetime = dt.strptime(value, format)
+                    except ValueError:
+                        continue
+
+                if datetime is None:
+                    raise ValueError(
+                        f"Could not parse date {repr(value)} with format {repr(cls.format)} or {repr(cls.secondary_formats)}"
+                    )
 
-            return Date(time.year, time.month, time.day)
+            return cls.from_datetime(datetime)
 
         from_str = core_schema.chain_schema(
             [
                 core_schema.str_schema(),
-                core_schema.no_info_plain_validator_function(to_date),
+                core_schema.no_info_plain_validator_function(to_datetime_cls),
             ]
         )
 
@@ -41,7 +56,7 @@ class Date:
             json_schema=from_str,
             python_schema=core_schema.union_schema(
                 [
-                    core_schema.is_instance_schema(Date),
+                    core_schema.is_instance_schema(cls),
                     from_str,
                 ]
             ),
@@ -49,3 +64,62 @@ class Date:
                 lambda date: str(date)
             ),
         )
+
+
+class Date(AbstractDateTime):
+    """Date is a custom type for representing dates in the format YYYYMMDD"""
+
+    format = "%Y%m%d"
+
+    year: int
+    month: int
+    day: int
+
+    def __init__(self, year: int, month: int, day: int):
+        self.year = year
+        self.month = month
+        self.day = day
+        self.datetime = dt(year, month, day)
+
+    @classmethod
+    def from_datetime(cls, datetime: dt):
+        return cls(datetime.year, datetime.month, datetime.day)
+
+
+class DateTime(AbstractDateTime):
+    """DateTime is a custom type for representing dates"""
+
+    # `%f` is padded to 6 characters but should be 9 overall.
+    format = "%Y-%m-%d %H:%M:%S.000%f%z"
+
+    # Same constructor as datetime has.
+    def __init__(
+        self,
+        year: SupportsIndex,
+        month: SupportsIndex,
+        day: SupportsIndex,
+        hour: SupportsIndex = 0,
+        minute: SupportsIndex = 0,
+        second: SupportsIndex = 0,
+        microsecond: SupportsIndex = 0,
+        tzinfo: tzinfo | None = None,
+        *,
+        fold: int = 0,
+    ):
+        self.datetime = dt(
+            year, month, day, hour, minute, second, microsecond, tzinfo, fold=fold
+        )
+
+    @classmethod
+    def from_datetime(cls, datetime: dt):
+        return cls(
+            datetime.year,
+            datetime.month,
+            datetime.day,
+            datetime.hour,
+            datetime.minute,
+            datetime.second,
+            datetime.microsecond,
+            datetime.tzinfo,
+            fold=datetime.fold,
+        )

mphapi/env.py

@@ -0,0 +1,24 @@
+import sys
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+
+def load_env():
+    path = Path(__file__)
+    root_dir = None
+    env_file = None
+    for parent in path.parents:
+        root_dir = parent
+        env_file = root_dir.joinpath(".env")
+        if env_file.exists():
+            break
+
+    if root_dir is None:
+        print("No .env file found", file=sys.stderr)
+        return
+
+    print(f"Using .env from {repr(str(root_dir))}.")
+
+    load_dotenv(root_dir.joinpath(".env"))
+    load_dotenv(root_dir.joinpath(".env.local"))

mphapi/pricing.py

@@ -3,6 +3,8 @@ from typing import Annotated, Optional
 
 from pydantic import BaseModel, Field
 
+from .client import PriceConfig
+from .date import DateTime
 from .fields import camel_case_model_config, field_name
 from .response import ResponseError
 
@@ -72,6 +74,7 @@ class MedicareSource(str, Enum):
     ManualPricing = "Manual Pricing"
     SNF = "SNF PPS"
     Synthetic = "Synthetic Medicare"
+    DMEFS = "DMEFS"
 
 
 class InpatientPriceDetail(BaseModel):
@@ -143,6 +146,25 @@ class OutpatientPriceDetail(BaseModel):
     """Wage index used for geographic adjustment"""
 
 
+class AllowedRepricingFormula(BaseModel):
+    """The formula used to calculate the allowed amount"""
+
+    medicare_percent: Optional[float] = None
+    """Percentage of the Medicare amount used to calculate the allowed amount"""
+
+    billed_percent: Optional[float] = None
+    """Percentage of the billed amount used to calculate the allowed amount"""
+
+    fee_schedule: Optional[float] = None
+    """Fee schedule amount used as the allowed amount"""
+
+    fixed_amount: Optional[float] = None
+    """Fixed amount used as the allowed amount"""
+
+    per_diem: Optional[float] = None
+    """Per diem rate used to calculate the allowed amount"""
+
+
 class ProviderDetail(BaseModel):
     """
     ProviderDetail contains basic information about the provider and/or locality used for pricing.
@@ -161,6 +183,12 @@ class ProviderDetail(BaseModel):
     locality: Optional[int] = None
     """Geographic locality number used for pricing"""
 
+    geographic_cbsa: Annotated[Optional[int], field_name("geographicCBSA")] = None
+    """Core-Based Statistical Area (CBSA) number for provider ZIP"""
+
+    state_cbsa: Annotated[Optional[int], field_name("stateCBSA")] = None
+    """State Core-Based Statistical Area (CBSA) number"""
+
     rural_indicator: Optional[RuralIndicator] = None
     """Indicates whether provider is Rural (R), Super Rural (B), or Urban (blank)"""
 
@@ -224,9 +252,6 @@ class LineEdits(BaseModel):
 
     model_config = camel_case_model_config
 
-    denial_or_rejection_text: Optional[str] = None
-    """The overall explanation for why this line item was denied or rejected by the claim editor"""
-
     procedure_edits: Optional[list[str]] = None
     """Detailed description of each procedure code edit error (from outpatient editor)"""
 
@@ -251,9 +276,6 @@ class LineEdits(BaseModel):
     revenue_edits: Optional[list[str]] = None
     """Detailed description of each revenue code edit error (from outpatient editor)"""
 
-    professional_edits: Optional[list[str]] = None
-    """Detailed description of each professional claim edit error"""
-
 
 class PricedService(BaseModel):
     """PricedService contains the results of a pricing request for a single service line"""
@@ -278,12 +300,18 @@ class PricedService(BaseModel):
     medicare_repricing_note: Optional[str] = None
     """Note explaining approach for pricing or reason for error"""
 
+    network_code: Optional[str] = None
+    """Code describing the network used for allowed amount pricing"""
+
     allowed_repricing_code: Optional[LineRepricingCode] = None
     """Explains the methodology used to calculate allowed amount"""
 
     allowed_repricing_note: Optional[str] = None
     """Note explaining approach for pricing or reason for error"""
 
+    allowed_repricing_formula: Optional[AllowedRepricingFormula] = None
+    """Formula used to calculate the allowed amount"""
+
     technical_component_amount: Optional[float] = None
     """Amount Medicare would pay for the technical component"""
 
@@ -305,6 +333,30 @@ class PricedService(BaseModel):
     payment_indicator: Optional[str] = None
     """Text which explains the type of payment for Medicare"""
 
+    discount_formula: Optional[str] = None
+    """The multi-procedure discount formula used to calculate the allowed amount (outpatient only)"""
+
+    line_item_denial_or_rejection_flag: Optional[str] = None
+    """Identifies how a line item was denied or rejected and how the rejection can be overridden (outpatient only)"""
+
+    packaging_flag: Optional[str] = None
+    """Indicates if the service is packaged and the reason for packaging (outpatient only)"""
+
+    payment_adjustment_flag: Optional[str] = None
+    """Identifies special adjustments made to the payment (outpatient only)"""
+
+    payment_adjustment_flag2: Optional[str] = None
+    """Identifies special adjustments made to the payment (outpatient only)"""
+
+    payment_method_flag: Optional[str] = None
+    """The method used to calculate the allowed amount (outpatient only)"""
+
+    composite_adjustment_flag: Optional[str] = None
+    """Assists in composite APC determination (outpatient only)"""
+
+    hcpcs_apc: Annotated[Optional[str], field_name("hcpcsAPC")] = None
+    """Ambulatory Payment Classification code of the line item HCPCS (outpatient only)"""
+
     payment_apc: Annotated[Optional[str], field_name("paymentAPC")] = None
     """Ambulatory Payment Classification"""
 
@@ -332,6 +384,9 @@ class Pricing(BaseModel):
     medicare_repricing_note: Optional[str] = None
     """Note explaining approach for pricing or reason for error"""
 
+    network_code: Optional[str] = None
+    """Code describing the network used for allowed amount pricing"""
+
     allowed_repricing_code: Optional[ClaimRepricingCode] = None
     """Explains the methodology used to calculate allowed amount (CON, RBP, SCA, or IFO)"""
 
@@ -359,8 +414,145 @@ class Pricing(BaseModel):
     pricer_result: Optional[str] = None
     """Pricer return details"""
 
+    price_config: Optional[PriceConfig] = None
+    """The configuration used for pricing the claim"""
+
     services: list[PricedService] = Field(min_length=1)
     """Pricing for each service line on the claim"""
 
     edit_error: Optional[ResponseError] = None
     """An error that occurred during some step of the pricing process"""
+
+
+class Step(str, Enum):
+    new = "New"
+    received = "Received"
+    pending = "Pending"
+    held = "Held"
+    error = "Error"
+    input_validated = "Input Validated"
+    provider_matched = "Provider Matched"
+    edit_complete = "Edit Complete"
+    medicare_priced = "Medicare Priced"
+    primary_allowed_priced = "Primary Allowed Priced"
+    network_allowed_priced = "Network Allowed Priced"
+    out_of_network = "Out of Network"
+    request_more_info = "Request More Info"
+    priced = "Priced"
+    returned = "Returned"
+
+
+class Status(str, Enum):
+    pending_claim_input_validation = "Claim Input Validation"
+    pending_claim_edit_review = "Claim Edit Review"
+    pending_provider_matching = "Provider Matching"
+    pending_medicare_review = "Medicare Review"
+    pending_medicare_calculation = "Medicare Calculation"
+    pending_primary_allowed_review = "Primary Allowed Review"
+    pending_network_allowed_review = "Network Allowed Review"
+    pending_primary_allowed_determination = "Primary Allowed Determination"
+    pending_network_allowed_determination = "Network Allowed Determination"
+
+
+class StepAndStatus(BaseModel):
+    model_config = camel_case_model_config
+
+    step: Step
+    status: Optional[Status] = None
+
+
+class ClaimStatus(StepAndStatus):
+    model_config = camel_case_model_config
+
+    updated_by: Optional[str] = None
+    updated_at: Optional[DateTime] = None
+    pricing: Optional[Pricing] = None
+    error: Optional[ResponseError] = None
+
+
+status_new = StepAndStatus(step=Step.new)
+"""created by TPA. We use the transaction date as a proxy for this date"""
+
+status_received = StepAndStatus(step=Step.received)
+"""received and ready for processing. This is modified date of the file we get from SFTP"""
+
+status_held = StepAndStatus(step=Step.held)
+"""held for various reasons"""
+
+status_error = StepAndStatus(step=Step.error)
+"""claim encountered an error during processing"""
+
+status_input_validated = StepAndStatus(step=Step.input_validated)
+"""claim input has been validated"""
+
+status_provider_matched = StepAndStatus(step=Step.provider_matched)
+"""providers in the claim have been matched to the provider system of record"""
+
+status_edit_complete = StepAndStatus(step=Step.edit_complete)
+"""claim has been edited and is ready for pricing"""
+
+status_medicare_priced = StepAndStatus(step=Step.medicare_priced)
+"""claim has been priced according to Medicare"""
+
+status_primary_allowed_priced = StepAndStatus(step=Step.primary_allowed_priced)
+"""claim has been priced according to the primary allowed amount (e.g. contract, RBP, etc.)"""
+
+status_network_allowed_priced = StepAndStatus(step=Step.network_allowed_priced)
+"""claim has been priced according to the allowed amount of the network"""
+
+status_out_of_network = StepAndStatus(step=Step.out_of_network)
+"""is out of network"""
+
+status_request_more_info = StepAndStatus(step=Step.request_more_info)
+"""return claim to trading partner for more information to enable correct processing"""
+
+status_priced = StepAndStatus(step=Step.priced)
+"""done pricing"""
+
+status_returned = StepAndStatus(step=Step.returned)
+"""returned to TPA"""
+
+status_pending_claim_input_validation = StepAndStatus(
+    step=Step.pending, status=Status.pending_claim_input_validation
+)
+"""waiting for claim input validation"""
+
+status_pending_claim_edit_review = StepAndStatus(
+    step=Step.pending, status=Status.pending_claim_edit_review
+)
+"""waiting for claim edit review"""
+
+status_pending_provider_matching = StepAndStatus(
+    step=Step.pending, status=Status.pending_provider_matching
+)
+"""waiting for provider matching"""
+
+status_pending_medicare_review = StepAndStatus(
+    step=Step.pending, status=Status.pending_medicare_review
+)
+"""waiting for Medicare amount review"""
+
+status_pending_medicare_calculation = StepAndStatus(
+    step=Step.pending, status=Status.pending_medicare_calculation
+)
+"""waiting for Medicare amount calculation"""
+
+status_pending_primary_allowed_review = StepAndStatus(
+    step=Step.pending, status=Status.pending_primary_allowed_review
+)
+"""waiting for primary allowed amount review"""
+
+status_pending_network_allowed_review = StepAndStatus(
+    step=Step.pending, status=Status.pending_network_allowed_review
+)
+"""waiting for network allowed amount review"""
+
+status_pending_primary_allowed_determination = StepAndStatus(
+    step=Step.pending, status=Status.pending_primary_allowed_determination
+)
+"""waiting for the primary allowed amount (e.g. contract, RBP rate, etc.) to be determined"""
+
+status_pending_network_allowed_determination = StepAndStatus(
+    step=Step.pending, status=Status.pending_network_allowed_determination
+)
+"""waiting for allowed amount from the network"""