feat(social-controllers): add the position-lifecycle stage of a trade

[xavier-brochard]

Explanation

A trading position moves through four events: it is opened, added to, reduced, and closed. Trade['intent'] only distinguishes two of them — exit covers both a partial trim and a full close — so a consumer cannot tell a trader who sold 10% of a position from one who sold out. In MetaMask Mobile's social feed that surfaced as a real defect: both announced "closed", and the row switched to realized P&L on the strength of the same wrong boolean.

The social-api already had the information to settle this (it classifies each fill server-side, using a per-position isOpen flag), but nothing in this package's types carried it. This PR adds the two fields that do:

• Trade['action'] — 'opened' | 'added' | 'reduced' | 'closed', the fill's stage in its position's lifecycle. Deliberately asset-agnostic: a client may render only a direction for spot tokens while still needing the full value, because it is what decides whether a row shows realized or current P&L.
• Position['isOpen'] — the API's own open/closed verdict. Stronger than a positionAmount === 0 check: it survives precision dust, and it distinguishes "no position" from "a position of size ~0". Perpetuals in particular retain a non-zero positionAmount after closing, so size alone cannot answer the question.

TradeAction is exported for consumers that branch on the value.

Both fields are optional, so this is not a breaking change. The social-api deploys independently of this package, so a response from a deployment that predates the fields must still validate — SocialService uses superstruct's permissive type(), and there is now a test pinning that a payload without them is accepted. Clients keep a local fallback that derives the stage from trade history for exactly this window.

References

• Jira: TSA-988
• Producer: va-mmcx-social-api PR adding TradeDto.action and PositionDto.isOpen
• Consumer: MetaMask Mobile PR rendering the four stages in the social feed and position views

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

🤖 Generated with Claude Code