feat: return commands

[RishabhS7]

Return commands and test cases

Summary by CodeRabbit

• New Features

  • Added three new CLI commands for managing transferable records: accept-returned, reject-returned, and return-to-issuer.
  • Each command supports network selection, secure wallet authentication, and optional remarks with encryption.

• Tests

  • Comprehensive test coverage added for new commands across multiple networks.

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

[coderabbitai]

📝 Walkthrough

Walkthrough

This change introduces three new CLI commands for title escrow workflows: accept-returned, reject-returned, and return-document. Each command provides end-to-end functionality including user input prompting, wallet/signer initialization, network-aware gas parameter handling, blockchain transaction execution via TradeTrustToken contracts, and receipt validation with Etherscan links. Comprehensive test suites cover multiple networks (astron, astrontestnet).

Changes

Cohort / File(s)	Summary
Title Escrow Commands src/commands/title-escrow/accept-returned.ts, src/commands/title-escrow/reject-returned.ts, src/commands/title-escrow/return-document.ts	Three new CLI command modules for TitleEscrow workflows. Each implements: command wiring (command/describe exports), interactive input prompting (network, token registry address, tokenId, wallet selection, optional remark/encryption key), handler orchestration with logging and transaction feedback, and core blockchain interaction (wallet resolution, contract connection, gas estimation with EIP-1559 support, transaction execution, receipt validation). All support dry-run mode and error handling.
Accept-Returned Tests tests/commands/title-escrow/acceptReturned.test.ts, tests/commands/title-escrow/acceptReturned-astron.test.ts, tests/commands/title-escrow/acceptReturned-astrontestnet.test.ts	Comprehensive test suites for the accept-returned command covering promptForInputs variations (encrypted wallet, keyFile, private key, environment variable), acceptReturnedDocumentHandler success and error flows, handler end-to-end orchestration, and acceptReturned blockchain invocation. Network-specific tests validate behavior on astron and astrontestnet. Extensive mocking of prompts, wallet utilities, and trustvc module.
Reject-Returned Tests tests/commands/title-escrow/rejectReturned.test.ts, tests/commands/title-escrow/rejectReturned-astron.test.ts, tests/commands/title-escrow/rejectReturned-astrontestnet.test.ts	Comprehensive test coverage for the reject-returned command including promptForInputs input modalities, rejectReturnedDocumentHandler transaction flows with remark and encryption handling, handler orchestration, and rejectReturned invocation verification. Network-specific tests validate astron and astrontestnet implementations.
Return-Document Tests tests/commands/title-escrow/returnDocument.test.ts, tests/commands/title-escrow/returnDocument-astron.test.ts, tests/commands/title-escrow/returnDocument-astrontestnet.test.ts	Full test coverage for the return-document command encompassing promptForInputs with multiple wallet input methods, returnDocumentToIssuerHandler success and error paths, handler end-to-end flow, and returnDocument blockchain interaction. Network-specific tests for astron and astrontestnet verify correct transaction handling and invocation.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant CLI as Command Handler
    participant Prompt as Input Prompter
    participant Wallet as Wallet/Signer
    participant Provider as Network Provider
    participant Contract as TradeTrustToken Contract
    participant Blockchain as Blockchain

    User->>CLI: Invoke command (accept/reject/return)
    CLI->>Prompt: promptForInputs()
    Prompt->>User: Interactive prompts (network, tokenId, etc.)
    User-->>Prompt: Provide input
    Prompt-->>CLI: TitleEscrowReturnDocumentCommand
    
    CLI->>Wallet: Resolve signer for network
    Wallet->>Provider: Get network ID
    Provider-->>Wallet: Network ID
    Wallet-->>CLI: Signer initialized
    
    CLI->>Provider: Check gas estimation capability
    Provider-->>CLI: Gas capability info
    
    alt Encrypt remark if key provided
        CLI->>CLI: Encrypt remark with key
    end
    
    alt Dry-run mode
        CLI->>Contract: Call callStatic (gas estimation)
        Contract-->>Provider: Estimate gas
        Provider-->>CLI: Gas cost
        CLI-->>User: Display estimated cost
    else Normal execution
        CLI->>Contract: Execute transaction (accept/reject/returnToIssuer)
        Contract->>Blockchain: Submit transaction
        Blockchain-->>Contract: Transaction hash
        Contract-->>CLI: Wait for receipt
        Blockchain->>Blockchain: Confirm transaction
        Blockchain-->>CLI: Receipt with status
        CLI->>CLI: Validate receipt
        CLI-->>User: Display Etherscan link & success
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Poem

🐰 Three commands hop and bounce with glee,
Accept, reject, return—a trinity!
Wallets dance with blockchain's song,
Gas fees handled sharp and strong,
Tests verify each hoppy deed,
Documents flow where trust will lead! 🌱

---

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Free

📥 Commits

Reviewing files that changed from the base of the PR and between f50ce1b and 7b45aa5.

📒 Files selected for processing (12)

• src/commands/title-escrow/accept-returned.ts
• src/commands/title-escrow/reject-returned.ts
• src/commands/title-escrow/return-document.ts
• tests/commands/title-escrow/acceptReturned-astron.test.ts
• tests/commands/title-escrow/acceptReturned-astrontestnet.test.ts
• tests/commands/title-escrow/acceptReturned.test.ts
• tests/commands/title-escrow/rejectReturned-astron.test.ts
• tests/commands/title-escrow/rejectReturned-astrontestnet.test.ts
• tests/commands/title-escrow/rejectReturned.test.ts
• tests/commands/title-escrow/returnDocument-astron.test.ts
• tests/commands/title-escrow/returnDocument-astrontestnet.test.ts
• tests/commands/title-escrow/returnDocument.test.ts

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

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.}

[tradetrustimda]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀