new-site/scripts/document_gen/templates/cpni_clec_reseller_generator.py

"""
Generate the FCC CPNI Annual Certification Letter — CLEC Reseller variant.

Customer Approval / Safeguards language adapted for a CLEC reseller that
purchases local exchange capacity wholesale and resells it under its own
brand. The reseller's CPNI obligations extend both to end-user CPNI it
directly handles AND to CPNI that flows down from the wholesale provider.
Safeguards therefore include contractual flow-down terms.

See module ``cpni_clec_generator`` for the shared 2026 statutory block.
"""
from __future__ import annotations

import logging
from datetime import datetime
from pathlib import Path
from typing import Optional

LOG = logging.getLogger("document_gen.cpni_clec_reseller")

try:
    from docx import Document
    from docx.shared import Pt, Inches, RGBColor
    from docx.enum.text import WD_ALIGN_PARAGRAPH
except ImportError:
    LOG.warning("python-docx not installed — CPNI CLEC-Reseller generation unavailable")
    Document = None  # type: ignore[assignment,misc]

_NAVY = RGBColor(0x1A, 0x27, 0x44) if Document else None

VARIANT_ID = "clec_reseller"
VARIANT_LABEL = "Competitive Local Exchange Carrier — Reseller"

MAX_FORFEITURE_PER_VIOLATION = "$251,322"
MAX_FORFEITURE_CAP = "$2,513,215"


def _set_spacing(paragraph, after_pt=6, before_pt=0):
    pf = paragraph.paragraph_format
    pf.space_after = Pt(after_pt)
    if before_pt:
        pf.space_before = Pt(before_pt)


def _heading(doc, text):
    p = doc.add_paragraph()
    r = p.add_run(text)
    r.font.size = Pt(12)
    r.bold = True
    r.font.color.rgb = _NAVY
    _set_spacing(p, after_pt=4, before_pt=8)


def _body(doc, text, bold=False, size=10):
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.LEFT
    r = p.add_run(text)
    r.font.size = Pt(size)
    r.bold = bold
    _set_spacing(p, after_pt=6)


def _checkbox(doc, label, checked=True):
    mark = "\u2611" if checked else "\u2610"
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.LEFT
    r = p.add_run(f"  {mark}  {label}")
    r.font.size = Pt(10)
    _set_spacing(p, after_pt=3)


def _spacer(doc):
    p = doc.add_paragraph()
    _set_spacing(p, after_pt=0)


def generate_cpni_clec_reseller(
    output_path: str,
    entity_name: str,
    frn: str = "",
    filer_id_499: str = "",
    officer_name: str = "",
    officer_title: str = "Chief Executive Officer",
    complaints_count: int = 0,
    complaints_description: str = "",
    has_data_broker_inquiries: bool = False,
    data_broker_description: str = "",
    reporting_year: int = 0,
    upstream_wholesale_provider: str = "",
    address_street: str = "",
    address_city: str = "",
    address_state: str = "",
    address_zip: str = "",
    contact_email: str = "",
    contact_phone: str = "",
    breaches: list[dict] | None = None,
    **_: dict,
) -> Optional[str]:
    if Document is None:
        LOG.error("python-docx not installed")
        return None
    if reporting_year == 0:
        reporting_year = datetime.now().year - 1
    breaches = breaches or []

    doc = Document()
    for s in doc.sections:
        s.top_margin = Inches(1); s.bottom_margin = Inches(1)
        s.left_margin = Inches(1.25); s.right_margin = Inches(1.25)

    today = datetime.now().strftime("%B %d, %Y")
    signer = officer_name or "Authorized Officer"
    title = officer_title or "Officer"
    upstream = upstream_wholesale_provider or "its wholesale underlying carrier(s)"

    tp = doc.add_paragraph(); tp.alignment = WD_ALIGN_PARAGRAPH.CENTER
    t = tp.add_run("CPNI Annual Certification Letter")
    t.font.size = Pt(14); t.bold = True; t.font.color.rgb = _NAVY
    _set_spacing(tp, after_pt=2)
    sp = doc.add_paragraph(); sp.alignment = WD_ALIGN_PARAGRAPH.CENTER
    s = sp.add_run(
        f"Competitive Local Exchange Carrier — Reseller  \u2014  "
        f"47 CFR \u00a7 64.2009  \u2014  Calendar Year {reporting_year}"
    )
    s.font.size = Pt(10); s.font.color.rgb = RGBColor(0x55, 0x55, 0x55)
    _set_spacing(sp, after_pt=8)

    _heading(doc, "1. Provider Information")
    lines = [f"Company Name: {entity_name}", f"Variant: {VARIANT_LABEL}"]
    if frn:
        lines.append(f"FCC Registration Number (FRN): {frn}")
    if filer_id_499:
        lines.append(f"FCC Form 499 Filer ID: {filer_id_499}")
    addr = ", ".join(filter(None, [address_street, address_city]))
    if address_state or address_zip:
        addr += f", {address_state} {address_zip}".strip()
    if addr.strip(", "):
        lines.append(f"Address: {addr.strip(', ')}")
    if contact_phone:
        lines.append(f"Telephone: {contact_phone}")
    if contact_email:
        lines.append(f"Email: {contact_email}")
    lines.append(f"Certifying Officer: {signer}, {title}")
    lines.append(f"Date of Filing: {today}")
    lines.append(f"Filing Deadline: March 2, {reporting_year + 1}")
    _body(doc, "\n".join(lines))

    _heading(doc, "2. Officer Statement of Personal Knowledge")
    _body(doc, (
        f"I, {signer}, {title} of {entity_name}, state that I have personal "
        f"knowledge of the matters certified herein. I have reviewed "
        f"{entity_name}'s CPNI operating procedures (including reseller "
        f"flow-down terms with upstream wholesale providers), and I have "
        f"examined supervisory logs and records covering the reporting "
        f"period. The representations herein are based on my personal "
        f"review and are true and correct to the best of my knowledge, "
        f"information, and belief."
    ))

    _heading(doc, "3. Certification of Compliance")
    _body(doc, (
        f"Pursuant to 47 CFR \u00a7 64.2009(e), {entity_name} hereby submits "
        f"its annual certification of compliance with the CPNI rules at "
        f"47 CFR \u00a7\u00a7 64.2001 through 64.2011 for the period "
        f"January 1, {reporting_year} through December 31, {reporting_year}. "
        f"{entity_name} has established, maintained, and adhered to "
        f"operating procedures that ensure compliance with these rules."
    ))

    _heading(doc, "4. How Our Procedures Ensure Compliance")
    _body(doc, (
        f"As a CLEC reseller purchasing wholesale local-exchange capacity "
        f"from {upstream} and reselling it under its own brand, {entity_name} "
        f"protects CPNI at two boundaries: (1) the retail end-user interface "
        f"where it directly handles customer records, and (2) the wholesale "
        f"flow from the underlying carrier(s). Specific procedures include:"
    ))
    _checkbox(doc, (
        "End-user customer authentication is required before any CPNI "
        "disclosure; authentication uses pre-established password or "
        "verification of non-CPNI account attributes (47 CFR \u00a7 64.2010)."
    ))
    _checkbox(doc, (
        "CPNI use beyond the scope of the subscribed service is permitted "
        "only after written or oral opt-in consent under 47 CFR \u00a7 64.2007, "
        "documented in the customer record."
    ))
    _checkbox(doc, (
        f"Reseller flow-down: {entity_name}'s wholesale-service agreement "
        f"with {upstream} expressly requires the upstream carrier to treat "
        f"all end-user CPNI received through {entity_name} in a manner "
        f"consistent with 47 CFR \u00a7\u00a7 64.2001\u201364.2011. "
        f"{entity_name} reviews upstream CPNI attestations annually."
    ))
    _checkbox(doc, (
        "The CPNI Protection Officer has oversight authority over both "
        "retail records systems and wholesale interconnect logs, and "
        "reviews upstream carrier breach notices per 47 CFR \u00a7 64.2011."
    ))
    _checkbox(doc, (
        "Changes to an end-user account (PIC, address-of-record, password) "
        "are confirmed to the customer's address of record before taking "
        "effect."
    ))
    _checkbox(doc, (
        "Access logs are maintained and reviewed at least quarterly; "
        "retention meets or exceeds two years for CPNI access and five "
        "years for certification records under 47 CFR \u00a7 64.2009."
    ))
    _checkbox(doc, (
        "Annual CPNI training is conducted for all personnel with CPNI "
        "access. Disciplinary procedures are documented and applied to "
        "any violation."
    ))

    _heading(doc, "5. Customer Complaints")
    if complaints_count == 0:
        _body(doc, (
            f"{entity_name} has NOT received any customer complaints during "
            f"the reporting period concerning the unauthorized release or "
            f"use of CPNI. Zero (0) complaints were logged."
        ))
    else:
        desc = complaints_description or (
            "Each complaint was investigated and resolved in accordance with "
            "the company's CPNI compliance procedures."
        )
        _body(doc, (
            f"{entity_name} HAS received {complaints_count} customer "
            f"complaint{'s' if complaints_count != 1 else ''} during the "
            f"reporting period. {desc}"
        ))

    _heading(doc, "6. Data Broker Inquiries and Pretexting")
    if not has_data_broker_inquiries:
        _body(doc, (
            f"{entity_name} has NOT received any inquiries, communications, "
            f"or attempts by data brokers or other unauthorized parties "
            f"seeking the unauthorized release of CPNI."
        ))
    else:
        desc = data_broker_description or (
            "Each such inquiry was refused, documented, and escalated."
        )
        _body(doc, (
            f"{entity_name} HAS received data broker or pretexting-style "
            f"inquiries during the reporting period. {desc}"
        ))

    _heading(doc, "7. Breach Log Summary")
    if not breaches:
        _body(doc, (
            f"{entity_name} experienced no CPNI breaches during the "
            f"reporting period. No 47 CFR \u00a7 64.2011 notifications were "
            f"required."
        ))
    else:
        _body(doc, (
            f"{entity_name} experienced {len(breaches)} CPNI breach"
            f"{'es' if len(breaches) != 1 else ''} during the reporting "
            f"period; each was reported to the Commission via the CPNI "
            f"Breach Reporting Portal within 7 business days."
        ))

    _heading(doc, "8. Penalties, Truthfulness, and Perjury Acknowledgment")
    _body(doc, (
        f"{entity_name} and the undersigned officer acknowledge that CPNI "
        f"rule violations may subject the carrier to monetary forfeitures "
        f"of up to {MAX_FORFEITURE_PER_VIOLATION} per violation and up to "
        f"{MAX_FORFEITURE_CAP} for any single act or failure to act "
        f"(adjusted per 47 CFR \u00a7 1.80)."
    ))
    _body(doc, (
        "Pursuant to 47 CFR \u00a7 1.17, the undersigned represents that "
        "no material factual information has been withheld and that all "
        "statements herein are truthful, accurate, and complete."
    ))
    _body(doc, (
        "The undersigned acknowledges that willful false statements in this "
        "certification are punishable under Title 18, U.S.C. \u00a7 1001, "
        "and by forfeiture under 47 U.S.C. \u00a7 503."
    ))

    _heading(doc, "9. Signature of Certifying Officer")
    _body(doc, (
        "I declare under penalty of perjury under the laws of the United "
        "States of America that the foregoing is true and correct."
    ))
    _spacer(doc)
    sig = doc.add_paragraph()
    sig.add_run("_" * 45).font.size = Pt(10)
    _set_spacing(sig, after_pt=2)
    nm = doc.add_paragraph()
    nr = nm.add_run(signer); nr.bold = True; nr.font.size = Pt(10)
    _set_spacing(nm, after_pt=2)
    tpp = doc.add_paragraph()
    tpp.add_run(f"{title}, {entity_name}").font.size = Pt(10)
    _set_spacing(tpp, after_pt=2)
    dp = doc.add_paragraph()
    dp.add_run(f"Date: {today}").font.size = Pt(10)
    _set_spacing(dp, after_pt=2)

    out = Path(output_path)
    out.parent.mkdir(parents=True, exist_ok=True)
    doc.save(str(out))
    LOG.info("CPNI CLEC-Reseller certification letter generated: %s", out)
    return str(out)