new-site/scripts/workers/services/npi_provider.py

"""Healthcare / NPI provider compliance handlers.

Review-staged: each NPI service generates an admin todo with the provider's
NPI + intake details for a human to file in CMS PECOS / NPPES. This mirrors the
FCC auto-filing-off safety default — no automated submission to government
portals until the Playwright flows are proven.

When the Playwright NPPES/PECOS flows are enabled, they must route through the
residential SOCKS proxy (CMS blocks datacenter IPs) by launching with
``undetected_browser(use_proxy="HEALTHCARE_PROXY_URL")`` — the credential
(username ``performancewest``) is configured via HEALTHCARE_PROXY_URL in .env.

Covers slugs:
  npi-revalidation            Medicare PECOS revalidation (5-yr cycle)
  npi-reactivation            reactivate a deactivated NPI
  nppes-update                NPPES data update / attestation
  medicare-enrollment         new Medicare enrollment via PECOS
  oig-sam-screening           OIG LEIE + SAM exclusion screening (annual)
  provider-compliance-bundle  revalidation watch + screening + NPPES upkeep

Intake data needed (collected by the npi-intake wizard step):
  - npi                provider's 10-digit NPI
  - provider_name      legal/provider name
  - email              contact email
  - pecos_enrollment_id (optional) PECOS enrollment ID
  - specialty          (optional) taxonomy/specialty
  - practice_state     (optional) practice location state
"""

from __future__ import annotations

import json
import logging
import os

LOG = logging.getLogger("workers.services.npi_provider")

# Per-slug admin todo metadata: human-readable action + the portal a human uses.
_SLUG_META = {
    "npi-revalidation": {
        "name": "Medicare PECOS Revalidation Filing",
        "portal": "https://pecos.cms.hhs.gov/",
        "action": (
            "File the Medicare revalidation in PECOS for this provider. Confirm "
            "the revalidation due date on the CMS revalidation list, update the "
            "enrollment record, and submit. Capture the PECOS tracking ID."
        ),
        "access": (
            "Standard (default): prepare CMS-855I/B, provider e-signs cert, mail to MAC (daily batch). "
            "Expedited (if surrogate granted at intake): file in PECOS via CMS I&A surrogate access, same-day tracking."
        ),
        "priority": "high",
    },
    "npi-reactivation": {
        "name": "NPI Reactivation",
        "portal": "https://nppes.cms.hhs.gov/",
        "action": (
            "Reactivate the deactivated NPI. Verify the deactivation "
            "reason, correct any stale data, and re-certify the record."
        ),
        "access": (
            "Standard (default): prepare CMS-855I (reactivation reason), provider e-signs, mail to MAC (daily batch). "
            "Expedited (if surrogate granted): reactivate online in PECOS/NPPES via I&A surrogate access."
        ),
        "priority": "high",
    },
    "nppes-update": {
        "name": "NPPES Data Update / Attestation",
        "portal": "https://nppes.cms.hhs.gov/",
        "action": (
            "Update + re-attest the provider's NPPES record (CMS requires "
            "updates within 30 days of any change). Apply the requested field "
            "changes and certify."
        ),
        "access": (
            "Standard (default): prepare CMS-10114 NPPES update, provider e-signs, mail to NPI Enumerator (Fargo, daily batch). "
            "Expedited (if surrogate granted): update online in NPPES via I&A surrogate access."
        ),
        "priority": "normal",
    },
    "medicare-enrollment": {
        "name": "Medicare Enrollment (PECOS)",
        "portal": "https://pecos.cms.hhs.gov/",
        "action": (
            "Complete the provider's Medicare enrollment in PECOS (CMS-855). "
            "Confirm taxonomy, practice location, and authorized official."
        ),
        "access": (
            "Standard (default): prepare CMS-855, provider e-signs cert, mail to MAC (daily batch). "
            "Expedited (if surrogate granted): file in PECOS via CMS I&A surrogate access, same-day tracking. "
            "NOTE: org (855B) enrollment/revalidation requires the CMS application fee paid via PECOS before submission."
        ),
        "priority": "high",
    },
    "oig-sam-screening": {
        "name": "OIG/SAM Exclusion Screening (Annual)",
        "portal": "https://oig.hhs.gov/exclusions/  +  https://sam.gov/",
        "action": (
            "Run the provider (and any listed staff) against the OIG LEIE and "
            "SAM exclusion lists. Produce the screening certificate and flag any "
            "matches for escalation."
        ),
        "access": (
            "No client access needed - OIG LEIE + SAM.gov are public. Screen by NPI/name, issue certificate."
        ),
        "priority": "normal",
    },
    "provider-compliance-bundle": {
        "name": "Provider Compliance Bundle (Annual)",
        "portal": "https://pecos.cms.hhs.gov/  +  https://nppes.cms.hhs.gov/",
        "action": (
            "Onboard the provider into the annual compliance bundle: enroll in "
            "revalidation watch, run OIG/SAM screening, and refresh the NPPES "
            "record. Set the next revalidation reminder."
        ),
        "access": (
            "Standard (default): CMS-855 paper filing for the enrollment/revalidation piece, mailed to MAC (daily batch); screening is public (no client action). "
            "Expedited (if surrogate granted): NPPES + PECOS pieces filed online via CMS I&A surrogate access."
        ),
        "priority": "high",
    },
}

# Slugs whose fulfilment includes a CMS-855 (auto-filled official form, signed
# via the secure e-sign link, then submitted to the provider's MAC via the daily
# batched mailing). The bundle's revalidation piece is handled by the dedicated
# revalidation order it spawns, so it is not listed here.
#
# nppes-update is intentionally NOT here: its Standard path is the CMS-10114 (NPPES
# update mailed to the NPI Enumerator in Fargo), handled by a separate filler when
# built. Until then, nppes-update falls to the admin todo (Expedited if surrogate
# granted, otherwise manual CMS-10114 prep).
_STANDARD_FILING_SLUGS = {
    "npi-revalidation",
    "npi-reactivation",
    "medicare-enrollment",
}


class _BaseNPIHandler:
    """Shared review-staged behaviour for all NPI services."""

    SERVICE_SLUG = ""

    async def process(self, order_data: dict) -> list[str]:
        order_number = order_data.get("order_number", order_data.get("name", ""))
        return await self.handle(order_data, order_number)

    async def handle(self, order_data: dict, order_number: str) -> list[str]:
        meta = _SLUG_META[self.SERVICE_SLUG]
        LOG.info("[%s] Processing %s", order_number, self.SERVICE_SLUG)

        intake = order_data.get("intake_data") or {}
        if isinstance(intake, str):
            intake = json.loads(intake)

        npi = intake.get("npi", "N/A")
        provider = intake.get("provider_name", order_data.get("customer_name", "Unknown"))
        specialty = intake.get("specialty", "")
        practice_state = intake.get("practice_state", "")
        pecos_id = intake.get("pecos_enrollment_id", "")
        customer_email = (
            intake.get("email")
            or order_data.get("customer_email")
            or order_data.get("email")
            or ""
        )

        # For PECOS enrollment/revalidation we generate the official CMS-855,
        # send it for e-signature, then a human submits it to the MAC.
        filing_note = ""
        if self.SERVICE_SLUG in _STANDARD_FILING_SLUGS:
            try:
                filing_note = self._generate_855_for_signing(
                    order_number, intake, provider, customer_email
                )
            except Exception as exc:  # never block the admin todo on PDF issues
                LOG.error("[%s] CMS-855 generation failed: %s", order_number, exc)
                filing_note = f"CMS-855 auto-generation FAILED ({exc}); prepare the form manually."

        description = (
            f"{meta['action']}\n\n"
            f"Provider: {provider}\n"
            f"NPI: {npi}\n"
            f"PECOS Enrollment ID: {pecos_id or 'not provided'}\n"
            f"Specialty: {specialty or 'not provided'}\n"
            f"Practice state: {practice_state or 'not provided'}\n"
            f"Portal: {meta['portal']}\n"
            f"Access model: {meta['access']}\n"
            + (f"\n{filing_note}\n" if filing_note else "")
            + "\nReview-staged: complete/verify the form, get it signed, then "
            "submit it to the provider's MAC (standard), or file in "
            "PECOS if surrogate access was granted). Mark this order complete."
        )

        self._create_todo(
            order_number,
            intake,
            title=f"{meta['name']} — {provider} (NPI {npi})",
            description=description,
            priority=meta["priority"],
        )
        return []

    def _generate_855_for_signing(self, order_number, intake, provider, customer_email) -> str:
        """Generate the official CMS-855, upload it, and request an e-signature.

        Returns a human-readable note for the admin todo describing what was
        generated and what still needs manual completion. The signed PDF is
        submitted to the MAC by the fulfilment team.
        """
        try:
            from scripts.document_gen.templates.cms855_pdf_filler import (
                determine_form_type, fill_cms855,
            )
        except ImportError:
            from document_gen.templates.cms855_pdf_filler import (  # type: ignore
                determine_form_type, fill_cms855,
            )

        form_type = determine_form_type(self.SERVICE_SLUG, intake)
        pdf_bytes, anchors, missing = fill_cms855(form_type, intake, order_number)

        # Upload the unsigned, partially-filled official form to MinIO.
        document_key = f"compliance/{order_number}/cms{form_type}_unsigned.pdf"
        try:
            import tempfile
            try:
                from scripts.document_gen.minio_client import MinioStorage
            except ImportError:
                from document_gen.minio_client import MinioStorage  # type: ignore
            storage = MinioStorage()
            with tempfile.NamedTemporaryFile(suffix=".pdf", delete=True) as tf:
                tf.write(pdf_bytes)
                tf.flush()
                storage.upload(tf.name, document_key, content_type="application/pdf")
        except Exception as exc:
            LOG.error("[%s] CMS-855 upload failed: %s", order_number, exc)
            return f"CMS-{form_type.upper()} generated but upload FAILED ({exc})."

        # Create the esign record (via the shared helper, which also emails the
        # signing link) and attach the official signature anchor so the stamper
        # lands the signature on the certification line.
        signed = self._create_855_esign_record(
            order_number, intake, provider, customer_email,
            form_type, document_key, anchors,
        )

        note_lines = [
            f"CMS-{form_type.upper()} generated (official form, auto-filled where possible).",
            f"Unsigned PDF: {document_key}",
        ]
        if signed and customer_email:
            note_lines.append(f"E-sign link emailed to {customer_email}. After signing, submit to the MAC (standard) or file via PECOS surrogate access (expedited).")
        else:
            note_lines.append("No customer email or esign infra — send the form for signature manually.")
        if missing:
            note_lines.append("MANUAL COMPLETION NEEDED:")
            note_lines.extend(f"  - {m}" for m in missing)
        return "\n".join(note_lines)

    def _create_855_esign_record(self, order_number, intake, provider, customer_email,
                                 form_type, document_key, anchors) -> bool:
        """Create the esign record + email the signing link via the shared helper,
        then attach the official signature anchors. Returns True on success.
        """
        if not customer_email:
            return False

        document_type = f"cms{form_type}"
        document_title = f"Medicare Enrollment Form (CMS-{form_type.upper()})"

        try:
            try:
                from scripts.workers.services.telecom.esign_helper import request_esign
            except ImportError:
                from .telecom.esign_helper import request_esign  # type: ignore
            import psycopg2

            conn = psycopg2.connect(os.environ.get("DATABASE_URL", ""))
            try:
                esign_id = request_esign(
                    conn=conn,
                    order_number=order_number,
                    document_type=document_type,
                    document_title=document_title,
                    entity_name=provider,
                    customer_email=customer_email,
                    customer_name=provider,
                    document_minio_key=document_key,
                    requires_perjury=True,
                    metadata={"service_slug": self.SERVICE_SLUG, "npi": intake.get("npi", ""), "form_type": form_type},
                    expires_hours=21 * 24,
                )
                # request_esign does not persist signature anchors; attach them so
                # the stamper places the signature on the certification line.
                if esign_id and anchors:
                    with conn.cursor() as cur:
                        cur.execute(
                            "UPDATE esign_records SET signature_anchors = %s, updated_at = NOW() WHERE id = %s",
                            (json.dumps(anchors), esign_id),
                        )
                    conn.commit()
                return esign_id is not None
            finally:
                conn.close()
        except Exception as exc:
            LOG.error("[%s] CMS-855 esign request failed: %s", order_number, exc)
            return False

    def _create_todo(self, order_number, intake, title, description, priority="normal"):
        try:
            import psycopg2

            conn = psycopg2.connect(os.environ.get("DATABASE_URL", ""))
            with conn.cursor() as cur:
                cur.execute(
                    """
                    INSERT INTO admin_todos (
                        title, category, priority, order_number, service_slug,
                        description, data, status
                    ) VALUES (%s, %s, %s, %s, %s, %s, %s, 'pending')
                    """,
                    (
                        title, "filing", priority, order_number,
                        self.SERVICE_SLUG, description, json.dumps(intake),
                    ),
                )
            conn.commit()
            conn.close()
        except Exception as exc:
            LOG.error("[%s] Failed to create NPI todo: %s", order_number, exc)


class NPIRevalidationHandler(_BaseNPIHandler):
    SERVICE_SLUG = "npi-revalidation"


class NPIReactivationHandler(_BaseNPIHandler):
    SERVICE_SLUG = "npi-reactivation"


class NPPESUpdateHandler(_BaseNPIHandler):
    SERVICE_SLUG = "nppes-update"


class MedicareEnrollmentHandler(_BaseNPIHandler):
    SERVICE_SLUG = "medicare-enrollment"


class OIGSAMScreeningHandler(_BaseNPIHandler):
    SERVICE_SLUG = "oig-sam-screening"


class ProviderComplianceBundleHandler(_BaseNPIHandler):
    SERVICE_SLUG = "provider-compliance-bundle"