Skip to content

refactor: parse item_fields into Pydantic models in all webhook handlers #55

@gillespied

Description

@gillespied

Context

In #54, the new handle_qa_review handler parses raw SharePoint item_fields dicts into a typed Pydantic model (SharepointInvitationQA) as its first step, using from_sharepoint_fields(). This gives us:

  • Pydantic validation up front (catches malformed data early)
  • SharePoint system fields (Modified, Created, AuthorLookupId, etc.) stripped automatically
  • Typed attribute access instead of .get() calls with default strings
  • Consistent serialisation when writing back via to_sharepoint_fields()

The existing make_list_review_handler (handle_review) and extract_actions_from_review still work with raw item_fields dicts throughout. This means:

  • No validation of incoming SharePoint data
  • Manual .get() calls with hardcoded defaults scattered across handler and component code
  • Risk of passing system fields through to downstream consumers

Proposal

Adopt the same pattern for the existing handlers:

  1. handle_review in route_handlers.py — parse item_fields into the appropriate SharePoint model (SharepointInvitation or SharepointSubmission depending on document_type) as the first step
  2. extract_actions_from_review in components.py — accept a typed model instead of a raw dict, build context strings from model attributes rather than .get() calls
  3. to_sharepoint_action in mappers.py — accept a typed source model instead of item_fields: dict

This would make from_sharepoint_fields() the standard entry point for all SharePoint data entering the handler pipeline.

Files affected

  • src/box2/receiver/route_handlers.pyhandle_review inner function
  • src/box2/pipeline/components.pyextract_actions_from_review(), context template formatting
  • src/box2/pipeline/mappers.pyto_sharepoint_action() signature

Notes

  • This is a refactor with no functional change — existing behaviour should be preserved
  • The from_sharepoint_fields utility and round-trip tests already exist from feat: add private office QA stage for invitations #54
  • The QA handler serves as the reference implementation for the pattern

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions