refactor(kyc-controller): reconcile getSessionStatus/fetchKyCstatus, userStatus/sessionStatus, and polling

[jiexi]

Explanation

Previously the kyc-controller had two separate UserStatus and KycStatus types which were basically the same. They also had two separate loops. This PR drops UserStatus in favor of KycStatus which is mostly referenced as sessionStatus now. Additionally, sessionId is now persisted in state. userStatus, userStatusSumsubSessionId, userStatusErrorCode have been removed from state in favor of sessionStatus

References

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

---

Note

High Risk
Multiple breaking public API and state-shape changes affect Money toast and KYC consumers; status now depends on a persisted session id and throws when it is missing.

Overview
This PR replaces the user-keyed GET /kyc/status path with the UKYC session status API. refreshKycStatus, KycController:statusChanged, and polling now use GET /sessions/{id}/status via getSessionStatus, and KycService.fetchKycStatus is removed.

State and types are consolidated: active sessionId (persisted) and sessionStatus move to the root of KycControllerState; userStatus and related fields are dropped. The simplified toast enum becomes KycSessionStatus; the full API payload is KycSessionStatusResponse.

Polling is merged onto a single loop driven by sessionStatusPollIntervalMs (replacing userStatusPollIntervalMs), shared by post-SDK decision waits and pending refreshKycStatus polls—with guards so terminal outcomes and reset() races are handled safely.

^{Reviewed by Cursor Bugbot for commit ae12050. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Terminal refresh leaves sub-flow polling

High Severity

Combining the poll loops lets refreshKycStatus stop the post-SDK wait when it sees a terminal sessionStatus, but that path records status without #updateSumSubOnTerminal. After a failed first poll — or a later consumer/consents refresh — sumsub.status can stay polling even though verification already finished.

Additional Locations (2)

• packages/kyc-controller/src/KycController.ts#L2181-L2205
• packages/kyc-controller/src/KycController.ts#L1323-L1331

 

^{Reviewed by Cursor Bugbot for commit adea851. Configure here.}

[jiexi]

only matters if you consume sumsub.status state which mobile does not currently do. I do not want to remove sumsub.status at this time because it requires unraveling more logic and this PR is plenty big already

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c8e9d72. Configure here.}

[cursor]

Stale session reused after restart

High Severity

Persisting sessionId makes startSumSub treat a leftover id as the current UKYC session and skip #createUkycSession. After a restart, initialize starts a fresh flow but does not clear that id, so the MoonPay path reuses the prior session for createJourney. A spent or rejected session can then fail the retry or be mapped to already-completed via session_not_in_valid_state.

Additional Locations (2)

• packages/kyc-controller/src/KycController.ts#L425-L430
• packages/kyc-controller/src/KycController.ts#L863-L903

 

^{Reviewed by Cursor Bugbot for commit c8e9d72. Configure here.}