procurement-ingest/lambdas/wo/shoc_emitter/envelope.py

"""Stream-record -> SHOC webhook envelope mapping (contract sections 3-4).

Pure and total for classification: no boto3 clients, no network. Table names
come from ``WORK_ORDERS_TABLE`` / ``COMMENTS_TABLE`` env (PLAT-11 kebab rename);
defaults preserve the pre-rename PascalCase names so unit tests without env
still pin the legacy stream ARNs. Every function either returns a value or
returns None (skip) -- a malformed stream record must never raise here;
classification gaps fall through to None so the shard is never blocked by an
unmappable record. ``build_event`` is the single entry point the handler calls
per record.

Classification (docs/shoc-webhook-contract.md section 4):
  work-orders / WorkOrders        INSERT -> work_order.created
  work-orders / WorkOrders        MODIFY -> work_order.cancelled iff OLD
      wo_status was not "cancelled" AND NEW wo_status is "cancelled",
      else work_order.updated
  work-order-comments / WorkOrderComments INSERT -> work_order.comment_added
  REMOVE (either table)    -> skip (no deletes in this pipeline)
  NEW write_origin == "shoc-write-api" -> skip (echo guard; a no-op branch
      today -- nothing writes that attribute yet -- kept so the phase-2
      write-back API never echoes SHOC's own writes back at it)
  comment_added with blank/missing text -> skip (email-processor #nocomment#
      rows; SHOC requires non-empty text and would 400-park them)
Anything else (unknown table, comment MODIFYs) -> skip.
"""

import os
from datetime import datetime, timezone
from decimal import Decimal

from boto3.dynamodb.types import TypeDeserializer

SCHEMA_VERSION = 1
SOURCE = "procurement-ingest/workorder-shoc-emitter"
CANCELLED_STATUS = "cancelled"
SHOC_WRITE_ORIGIN = "shoc-write-api"
# Defaults match pre-PLAT-11 physical names; TF/Lambda env overrides at cutover.
WORK_ORDERS_TABLE = os.environ.get("WORK_ORDERS_TABLE", "WorkOrders")
COMMENTS_TABLE = os.environ.get("COMMENTS_TABLE", "WorkOrderComments")

# data payload field lists (contract sections 4.1 / 4.2). Absent attributes are
# null-filled; source_email_s3_key is deliberately EXCLUDED (internal key, not
# part of the contract).
WO_DATA_FIELDS = (
    "work_order_id",
    "wo_status",
    "description",
    "customer",
    "site_code",
    "building",
    "address",
    "severity",
    "priority",
    "assigned_to",
    "date_reported",
    "scheduled_start",
    "due_date",
    "record_type",
    "created_at",
    "updated_at",
)
COMMENT_DATA_FIELDS = (
    "work_order_id",
    "comment_id",
    "record_type",
    "commenter",
    "text",
    "created_at",
    "ingested_at",
)

_deserializer = TypeDeserializer()
# arn:aws:dynamodb:...:table/NAME[/stream/LABEL] -- slash-split needs at least
# the ":table" head plus the name segment for the parse to be meaningful.
_MIN_ARN_SLASH_SEGMENTS = 2


def _plain(value):
    """Convert TypeDeserializer output to json.dumps-safe plain Python.

    Mirrors lambdas/api/serialization.py: integral Decimals become JSON
    integers (exact), non-integral Decimals become floats, sets become sorted
    lists. Local copy on purpose -- the emitter bundles flat and must not grow
    a cross-package import for twelve lines of logic.
    """
    if isinstance(value, Decimal):
        if value == value.to_integral_value():
            return int(value)
        return float(value)
    if isinstance(value, dict):
        return {key: _plain(item) for key, item in value.items()}
    if isinstance(value, list):
        return [_plain(item) for item in value]
    if isinstance(value, set):
        return sorted(_plain(item) for item in value)
    return value


def _deserialize_image(image: dict) -> dict:
    """DynamoDB stream image (attribute-value encoded) -> plain dict."""
    return {key: _plain(_deserializer.deserialize(av)) for key, av in image.items()}


def _table_name(event_source_arn: str) -> str | None:
    """Extract the exact table-name segment from a stream eventSourceARN.

    ARN format: arn:aws:dynamodb:region:acct:table/NAME/stream/LABEL. Parsing
    the segment exactly (not a loose substring) matters: legacy "WorkOrders"
    is a leading substring of "WorkOrderComments", and kebab "work-orders" is
    similarly adjacent to "work-order-comments" -- segment equality can't.
    """
    parts = event_source_arn.split("/")
    if len(parts) >= _MIN_ARN_SLASH_SEGMENTS and parts[0].endswith(":table"):
        return parts[1]
    return None


def _classify(table, event_name, new_image, old_image) -> str | None:
    if table == WORK_ORDERS_TABLE:
        if event_name == "INSERT":
            return "work_order.created"
        if event_name == "MODIFY":
            was_cancelled = old_image.get("wo_status") == CANCELLED_STATUS
            if not was_cancelled and new_image.get("wo_status") == CANCELLED_STATUS:
                return "work_order.cancelled"
            return "work_order.updated"
        return None
    if table == COMMENTS_TABLE and event_name == "INSERT":
        return "work_order.comment_added"
    return None


def _is_blank_comment_text(value) -> bool:
    """True when comment text is missing, empty, or whitespace-only."""
    return value is None or (isinstance(value, str) and not value.strip())


def is_blank_comment_skip(record: dict) -> bool:
    """True when this stream record is a blank-text comment_added skip.

    Used by the handler to emit a specific structured log for empty-comment
    skips (distinct from REMOVE / echo guard / unmappable). Safe to call on
    any record; returns False unless the record classifies as comment_added
    with blank/missing text.
    """
    event_name = record.get("eventName")
    if event_name == "REMOVE":
        return False
    stream = record.get("dynamodb") or {}
    new_image = _deserialize_image(stream.get("NewImage") or {})
    if new_image.get("write_origin") == SHOC_WRITE_ORIGIN:
        return False
    table = _table_name(record.get("eventSourceARN") or "")
    old_image = _deserialize_image(stream.get("OldImage") or {})
    if _classify(table, event_name, new_image, old_image) != "work_order.comment_added":
        return False
    return _is_blank_comment_text(new_image.get("text"))


def build_event(record: dict) -> dict | None:
    """Map one DynamoDB stream record to a webhook envelope, or None to skip."""
    event_name = record.get("eventName")
    if event_name == "REMOVE":
        return None
    stream = record.get("dynamodb") or {}
    new_image = _deserialize_image(stream.get("NewImage") or {})
    if new_image.get("write_origin") == SHOC_WRITE_ORIGIN:
        return None  # echo guard (forward-compat, contract section 3)
    table = _table_name(record.get("eventSourceARN") or "")
    old_image = _deserialize_image(stream.get("OldImage") or {})
    event_type = _classify(table, event_name, new_image, old_image)
    if event_type is None:
        return None
    if event_type == "work_order.comment_added":
        if _is_blank_comment_text(new_image.get("text")):
            return None
        fields = COMMENT_DATA_FIELDS
    else:
        fields = WO_DATA_FIELDS
    # eventID and ApproximateCreationDateTime are present on every real
    # DynamoDB stream record; guarding them keeps this function total (the
    # "never raise" contract above) rather than trusting a hard subscript.
    event_id = record.get("eventID")
    approx_creation = stream.get("ApproximateCreationDateTime")
    if event_id is None or approx_creation is None:
        return None
    # ApproximateCreationDateTime arrives as epoch seconds (float/Decimal).
    occurred_at = datetime.fromtimestamp(
        float(approx_creation), tz=timezone.utc
    ).isoformat()
    return {
        "schema_version": SCHEMA_VERSION,
        "delivery_id": event_id,
        "event_type": event_type,
        "occurred_at": occurred_at,
        "source": SOURCE,
        "replay": False,
        "data": {field: new_image.get(field) for field in fields},
    }