Resolve conflicting Escrow type definitions between types.ts and types/index.ts

[meshackyaro]

Description

The SDK defines two entirely different, incompatible Escrow type systems for the same domain concept:

• src/types.ts (top-level file): Escrow/EscrowStatus with fields sender, recipient, amount
• src/types/index.ts (folder barrel): EscrowState/EscrowParams with fields depositor, beneficiary, amountXLM — naming that actually matches the rest of the ecosystem (backend, contract)

src/index.ts does export * from './types'. Because Node/TypeScript module resolution prefers a file (types.ts) over a same-named directory (types/) when both exist, this line resolves to the top-level file — meaning src/types/index.ts is never actually exported from the package's public API, despite src/types/contract.ts, types/events.ts, and types/multisig.ts being explicitly re-exported separately from the same folder. Any consumer importing Escrow from @trustflow/sdk today silently gets the sender/recipient/amount shape, not the depositor/beneficiary/amountXLM shape used everywhere else in the protocol.

Component

SDK

Difficulty

🔴 Hard

Tasks

• Determine which type definition is canonical — types/index.ts's naming (depositor/beneficiary/amountXLM) matches the backend and contract conventions, so it's likely the intended one, but confirm against actual contract/backend usage
• Consolidate to a single definition, removing or renaming the shadowed/losing file
• Audit every internal usage of Escrow, EscrowStatus, CreateEscrowParams, etc. across src/escrow/*.ts to confirm which type they're actually resolving to today (this may reveal internal inconsistencies too)
• Add a build-time or lint check (e.g. an ESLint rule or a tsup/tsc config check) to catch future file/folder name collisions like this
• Bump the SDK's version appropriately (this is a breaking type change for any consumer relying on the currently-exported shape)

Acceptance Criteria

• Only one Escrow type definition exists and is exported from the package entrypoint
• All internal SDK code consistently uses the consolidated type with no silent mismatches
• A regression test or lint rule prevents a top-level file and a same-named folder from silently shadowing each other again
• CHANGELOG/README call out the breaking change if the consolidated shape differs from what was previously exported

Estimated Time

2-3 days

[telemarkdigital-publisher]

I can work on this if available. Plan: audit package entrypoint/module resolution to identify the canonical Escrow type, consolidate the public Escrow exports around the backend/contract-aligned shape, update internal SDK imports/usages, add a regression check for file/folder name collisions, and document the breaking type change in README/CHANGELOG. Expected verification commands: npm test, npm run build, npm run lint, and a targeted type-export regression test. I will wait for maintainer or GrantFox assignment before substantial implementation.