example_data_creation_log_helpers.py

"""Helpers for the optional audit log of example data creation, kept in a dynamic entity on OBP.

This module defines a single dynamic entity named after this application
(`ogcr_dynamicentities_log`, in the same space as the other entities -- see
obp_space.py) and the helpers needed to (a) make sure it exists on OBP and
(b) write one log record to it per event while example data is being created. It is
consumed by `create_example_data.py`, only when that is run with `--log` (logging
is off by default, and recreate_dynamic_entities.sh does not turn it on). It records:
  - `entity_created`  one record per successfully created object;
  - `entity_failed`   one record per object that failed to POST.

Each record carries a json `references` field listing every `reference:<x>` field
on the entity and how it resolved — `resolved` when a real created id was used, or
`fallback` when the spreadsheet example value was used instead (the reference
target was a static OBP entity or one we don't create here; see build_payload).

Logging is best-effort: every helper here swallows its own errors and never
raises, so recording the audit trail can never break the creation flow it
observes.
"""
import datetime
import logging


from obp_client import obp_host, session, authorization
from obp_space import record_path
from obp_dynamic_api import (
    create_system_dynamic_entity,
    get_dynamic_entity_id_by_name,
)

logger = logging.getLogger(__name__)

# Name the log entity after this application (lowercase, underscores only).
APP_NAME = "ogcr_dynamicentities"
LOG_ENTITY_NAME = f"{APP_NAME}_log"

# Event types written to the log entity's `event_type` field.
EVENT_CREATED = "entity_created"
EVENT_FAILED = "entity_failed"

# Example value for the `references` json field, documenting its shape.
_REFERENCES_EXAMPLE = [
    {
        "field": "operator_id",
        "target": "operator",
        "resolution": "resolved",
        "value": "a8770fca-3d1d-47af-b6d0-7a6c3f124388",
    },
    {
        "field": "bank_account_id",
        "target": "BankAccount",
        "resolution": "fallback",
        "value": "sample-account-id",
    },
]


def _string_prop(example, description):
    return {"type": "string", "example": example, "description": description}


def build_log_entity_definition():
    """Return the system-dynamic-entity definition for the creation log."""
    return {
        "hasPersonalEntity": False,
        "hasCommunityAccess": False,
        LOG_ENTITY_NAME: {
            "description": (
                "Audit log of OGCR dynamic-entity data creation: one record per "
                "created object or failed create, capturing how each of its "
                "reference fields resolved."
            ),
            "required": ["event_type", "entity_name"],
            "properties": {
                "event_type": _string_prop(
                    EVENT_CREATED,
                    f"One of {EVENT_CREATED}, {EVENT_FAILED}.",
                ),
                "entity_name": _string_prop(
                    "operator", "Name of the dynamic entity the event concerns."
                ),
                "entity_id": _string_prop(
                    "a8770fca-3d1d-47af-b6d0-7a6c3f124388",
                    "Id of the created object, when known.",
                ),
                "status": _string_prop("success", "success or error."),
                "message": _string_prop(
                    "Created operator", "Human-readable detail or error text."
                ),
                "references": {
                    "type": "json",
                    "example": _REFERENCES_EXAMPLE,
                    "description": (
                        "List of every reference:<x> field on this entity and how "
                        "it resolved. Each item has `field`, `target`, `resolution` "
                        "(resolved = a real created id was used; fallback = the "
                        "spreadsheet example value was used) and the `value` posted."
                    ),
                },
                "timestamp": _string_prop(
                    "2026-06-24T12:00:00Z",
                    "UTC ISO-8601 time the event was recorded.",
                ),
            },
        },
    }


def ensure_log_entity(token=None, base_url=None):
    """Make sure the log entity exists, creating it if needed.

    Returns the dynamicEntityId (or the entity name as a truthy sentinel) when
    the entity is available for posting, else None. Never raises.
    """
    try:
        existing = get_dynamic_entity_id_by_name(
            LOG_ENTITY_NAME, token=token, base_url=base_url
        )
        if existing:
            logger.info(f"Log entity '{LOG_ENTITY_NAME}' already exists (id: {existing})")
            return existing
        resp = create_system_dynamic_entity(
            build_log_entity_definition(), token=token, base_url=base_url
        )
        ent_id = resp.get("dynamicEntityId") if isinstance(resp, dict) else None
        logger.info(f"Created log entity '{LOG_ENTITY_NAME}' (id: {ent_id})")
        return ent_id or LOG_ENTITY_NAME
    except Exception as e:
        detail = getattr(getattr(e, "response", None), "text", None) or str(e)
        logger.error(f"Could not ensure log entity '{LOG_ENTITY_NAME}': {detail}")
        return None


def _now_iso():
    return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")


def log_event(
    event_type,
    entity_name,
    entity_id="",
    references=None,
    status="",
    message="",
    token=None,
    base_url=None,
):
    """POST a single record to the log dynamic entity.

    `references` is a list of `{field, target, resolution, value}` dicts (one per
    reference field on the entity); it is stored in the json `references` field.

    Best-effort: any failure is warned about and swallowed (returns None) so
    logging never breaks the data-creation flow.
    """
    base_url = base_url or obp_host
    record = {
        "event_type": event_type,
        "entity_name": entity_name,
        "entity_id": str(entity_id or ""),
        "status": status or "",
        "message": message or "",
        "references": references if references is not None else [],
        "timestamp": _now_iso(),
    }
    url = f"{base_url}{record_path(LOG_ENTITY_NAME)}"
    headers = {"Content-Type": "application/json"}
    if token:
        headers["Authorization"] = authorization(token)
    try:
        resp = session.post(url, headers=headers, json=record)
        resp.raise_for_status()
        return resp.json()
    except Exception as e:
        detail = getattr(getattr(e, "response", None), "text", None) or str(e)
        logger.warning(
            f"Failed to write {event_type} log record for {entity_name}: {detail}"
        )
        return None