feat: show collateral in credit agreements

[maschad]

• Closes https://linear.app/ardaglobal/issue/ARDGBL-982/update-deal-confirmation-page-on-platform

Summary by CodeRabbit

• New Features

  • Added collateral and covenant information display in deal review workflows.
  • New API endpoints to query document-level collateral and covenant data.
  • Enhanced deal extraction with intelligent multi-source payload detection and auto-selection of high-confidence matches.

• Improvements

  • Refined UI formatting and text clarity across modals.
  • Improved party data transformation for more accurate originator/investor handling.
  • Extended document status response with extraction result metadata.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[linear]

ARDGBL-982 Update Deal Confirmation Page on platform

We want to ensure that when someone is confirming a deal, it shows all the collaterals, all the covenants, and all the details of the credit agreement, before someone confirms that deal, which would be created from the credit agreement in Jeshall.

[coderabbitai]

Walkthrough

The changes expand deal data extraction capabilities by introducing new API endpoints for collateral and covenant information, implementing comprehensive deal payload normalization logic with multi-source evaluation, and enhancing UI components to fetch and display extracted party and deal data with improved loading state management.

Changes

Cohort / File(s)	Summary
Modal Components src/credit/components/company/SelectPartyModal.tsx, src/credit/components/deals/ExtractionReviewModal.tsx	SelectPartyModal: Adds useEffect to POST extraction telemetry on modal open; minor UI text consolidation and formatting refactoring. ExtractionReviewModal: Introduces utility helpers (tryParseJson, cleanNumber, formatMoney); adds state and loading flags for collateral/covenant data; fetches collateral/covenant info and processes deal matching with auto-selection of high-confidence matches.
Deal Extraction Logic src/credit/hooks/useExtractionDealCreation.ts	Implements comprehensive deal payload transformation: adds buildPartyObject for nested party structures, introduces scoreDealPayload and findBestDealPayload for multi-source evaluation, implements normalizeExtractionPayload with unwrapping heuristics. Shifts extraction flow from relying on dealPreview to evaluating multiple sources (document status, extraction_results, deal_extraction, deal_tape_data) with candidate scoring and logging scaffolding.
API & Type Definitions src/shared/lib/endpoints/ingestion.ts	Extends DocumentStatusResponse with deal_extraction, deal_extraction_error, and extraction_results fields. Introduces CollateralQueryResponse and CovenantQueryResponse interfaces. Adds IngestionAPI methods: getDocumentCollaterals and getDocumentCovenants with query parameter support for filtering.

Sequence Diagram

sequenceDiagram
    actor User
    participant ExtractionReviewModal
    participant useExtractionDealCreation
    participant IngestionAPI
    participant Backend

    User->>ExtractionReviewModal: Opens modal
    ExtractionReviewModal->>ExtractionReviewModal: useEffect triggered
    
    par Parallel Fetching
        ExtractionReviewModal->>IngestionAPI: getDocumentCollaterals()
        ExtractionReviewModal->>IngestionAPI: getDocumentCovenants()
        ExtractionReviewModal->>useExtractionDealCreation: Evaluate extraction sources
    end
    
    IngestionAPI->>Backend: GET /documents/{id}/collaterals
    IngestionAPI->>Backend: GET /documents/{id}/covenants
    Backend-->>IngestionAPI: Return collateral data
    Backend-->>IngestionAPI: Return covenant data
    
    useExtractionDealCreation->>useExtractionDealCreation: Normalize extraction payload<br/>(multi-source evaluation)
    useExtractionDealCreation->>useExtractionDealCreation: Score candidates<br/>(principal, names, etc.)
    useExtractionDealCreation->>useExtractionDealCreation: Select best deal payload
    
    IngestionAPI-->>ExtractionReviewModal: CollateralQueryResponse
    IngestionAPI-->>ExtractionReviewModal: CovenantQueryResponse
    useExtractionDealCreation-->>ExtractionReviewModal: Processed deal data +<br/>party information
    
    ExtractionReviewModal->>User: Display collaterals,<br/>covenants & matched deals

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

• useExtractionDealCreation.ts requires careful attention: complex multi-path payload transformation with scoring logic, multiple fallback strategies (principal_amount vs facility_amount), nested object parsing, and heuristic-based payload selection across multiple data sources. The candidate scoring and normalization functions warrant thorough validation.
• ExtractionReviewModal.tsx: New concurrent data-fetching patterns and loading state management across multiple data types (collaterals, covenants, deals) may introduce race conditions or edge cases; verify proper error handling and empty state flows.
• ingestion.ts: API contract changes introduce new response types; ensure backward compatibility and validate query parameter construction for collateral/covenant endpoints.
• Cross-layer integration: Changes span API layer, business logic, and UI; verify that data flows correctly through each layer and that telemetry/logging correctly captures the new extraction logic.

Poem

🐰 We hop through extraction's garden bright,
Collaterals and covenants in sight,
Deal payloads scored with careful thought,
Multi-source wisdom we have sought!
From API to UI, the data flows,
Where party and promise together rose. 🌱

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Free

📥 Commits

Reviewing files that changed from the base of the PR and between 8edc0b8 and 8daf753.

⛔ Files ignored due to path filters (1)

• .cursor/debug.log is excluded by !**/*.log

📒 Files selected for processing (4)

• src/credit/components/company/SelectPartyModal.tsx (9 hunks)
• src/credit/components/deals/ExtractionReviewModal.tsx (53 hunks)
• src/credit/hooks/useExtractionDealCreation.ts (5 hunks)
• src/shared/lib/endpoints/ingestion.ts (4 hunks)

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}