"""FCC Form 499-Q Quarterly Filing Handler. Simplified filing: the client submits quarterly revenue via the intake page, and this handler files it at USAC E-File. Revenue calculations are minimal compared to the 499-A — just four revenue buckets projected for the quarter. The 499-Q determines quarterly USF contribution payments. """ from __future__ import annotations import logging import os from datetime import datetime from .base_handler import BaseComplianceHandler logger = logging.getLogger("workers.services.form_499q") class Form499QHandler(BaseComplianceHandler): SERVICE_SLUG = "fcc-499q" SERVICE_NAME = "FCC Form 499-Q Quarterly Filing" async def process(self, order_data: dict) -> dict | None: order_number = order_data.get("order_number", "") entity = order_data.get("entity", {}) intake_data = order_data.get("intake_data", {}) if not intake_data.get("intake_completed"): logger.info( "Form499QHandler: %s intake not completed — waiting for client", order_number, ) self._create_admin_todo( order_number, f"499-Q {intake_data.get('quarter', '?')} for " f"{entity.get('legal_name', '?')} — awaiting client intake. " f"Due {intake_data.get('due_date', '?')}.", ) return None quarter = intake_data.get("quarter", "?") revenue = intake_data.get("revenue", {}) filer_id = intake_data.get("filer_id_499") or entity.get("filer_id_499", "") frn = intake_data.get("frn") or entity.get("frn", "") logger.info( "Form499QHandler: processing %s %s for %s (total: $%.2f)", order_number, quarter, entity.get("legal_name", "?"), revenue.get("total", 0), ) # Create admin todo with filing instructions # (Full Playwright automation for USAC E-File 499-Q TBD) self._create_admin_todo( order_number, f"FILE 499-Q {quarter} for {entity.get('legal_name', '?')} " f"(FRN: {frn}, Filer ID: {filer_id})\n\n" f"Revenue:\n" f" Carrier's Carrier Interstate: ${revenue.get('carriers_carrier_interstate', 0):.2f}\n" f" Carrier's Carrier Intrastate: ${revenue.get('carriers_carrier_intrastate', 0):.2f}\n" f" End-User Interstate: ${revenue.get('end_user_interstate', 0):.2f}\n" f" End-User Intrastate: ${revenue.get('end_user_intrastate', 0):.2f}\n" f" Total: ${revenue.get('total', 0):.2f}\n\n" f"Due: {intake_data.get('due_date', '?')}\n" f"Parent 499-A: {intake_data.get('parent_499a_order', '?')}\n\n" f"File at: https://forms.universalservice.org/", ) # Send confirmation email to client self._send_confirmation_email( to=entity.get("contact_email") or order_data.get("customer_email", ""), entity_name=entity.get("legal_name", ""), order_number=order_number, quarter=quarter, due_date=intake_data.get("due_date", ""), ) return {"status": "submitted_for_filing"} def _send_confirmation_email( self, to: str, entity_name: str, order_number: str, quarter: str, due_date: str, ) -> None: if not to: return try: import smtplib from email.mime.multipart import MIMEMultipart from email.mime.text import MIMEText subject = f"499-Q {quarter} Filing Received — {entity_name}" html = f"""

Form 499-Q {quarter} — Filing Received

Your FCC Form 499-Q quarterly revenue data for {entity_name} ({quarter}, due {due_date}) has been received.

We'll file this with USAC E-File and send you a confirmation with your filing reference number once complete.

Order: {order_number}
Questions? Reply to this email or contact ops@performancewest.net.

""" msg = MIMEMultipart("alternative") msg["From"] = os.environ.get("SMTP_FROM", "Performance West ") msg["To"] = to msg["Subject"] = subject msg.attach(MIMEText(html, "html")) with smtplib.SMTP( os.environ.get("SMTP_HOST", "co.carrierone.com"), int(os.environ.get("SMTP_PORT", "587")), timeout=30, ) as s: s.starttls() s.login( os.environ.get("SMTP_USER", ""), os.environ.get("SMTP_PASS", ""), ) s.send_message(msg) except Exception as exc: logger.warning("499-Q confirmation email failed: %s", exc)