"""Asking the sender for the one thing that was missing.

THE ONLY MESSAGE THIS SOFTWARE EVER SENDS

Until now the agent has never sent a WhatsApp message — `MessageSender` existed
and nothing called it. That is worth stating plainly, because the failure mode
here is not a missed notification. It is a loop: a retried workflow, a restarted
daemon or a redelivered webhook turning one question into forty, overnight, from
a business number that can be banned for exactly that.

So the permission to send is not held here. The CMS hands out a `notify`
instruction on the first response for an unidentified document and never again
— it stamps the row as it answers. This module has no memory and needs none: if
it is called, it sends; it is simply never called twice for the same document.

WHY THE REPLY MUST CARRY THE REFERENCE

A self-chat has no threading. When "35201-1234567-1" arrives an hour later there
is nothing in the message tying it to a document, and the only ways to guess are
"the most recent one" or "the oldest one waiting". Both are wrong the moment two
documents are waiting — and being wrong here files one client's bank statement
onto another client's record, silently, with a success message.

So the message asks for the reference back, and the parser requires it.
"""

from __future__ import annotations

from app.whatsapp.messages import OutboundMessage


def missing_information(recipient: str, reference: str, required: str, document: str = "Document") -> OutboundMessage:
    """The one message: what arrived, what it needs, and both ways to answer.

    Written to be read on a phone, in a hurry, by somebody who may not have sent
    the document themselves. The reference goes on its own line because it is
    the part that has to be typed back accurately, and the example shows the
    exact shape a reply must take rather than describing it.
    """
    body = "\n".join([
        f"{document} received.",
        "",
        f"Reference: {reference}",
        "",
        f"To file it we need: {required}.",
        "",
        "Reply with the reference and the number, for example:",
        f"{reference} 35201-1234567-1",
        "",
        "Or open TaxPilot CMS → TaxPilot AI → Waiting for Information.",
    ])

    return OutboundMessage(recipient=recipient, text=body)