feat(kyc-controller): restore existing session for vendor

[jiexi]

• Add getLatestSessionStatusForVendor to KycService
• finalStatus enum updated
• Fix status type
• persist sessionStatus
• reuse existing session if available

Explanation

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 changes to KYC state shape, persistence, status semantics, and SumSub launch rules affect identity flows and downstream consumers that read sessionStatus or KycSumSubStatus.

Overview
Adds KycService.getLatestSessionStatusForVendor (GET /sessions/latest/status/{vendor}), returning the same status payload as getSessionStatus or null on HTTP 404.

KycController uses that lookup during initialize (when state has no sessionId) and before creating a UKYC session in startSumSub / the consents path, so at most one session per vendor is reused instead of creating another. An existing session’s status is stored for any finalStatus; when it is already approved, the flow finishes at done and SumSub is not launched.

Breaking behavior changes: session outcomes are driven by sessionStatus.finalStatus only (new | pending | approved | rejected | retry); kycStatus is stored but ignored. sessionStatus is now persisted and cleared together with sessionId via clearUkycSession. vendorProcessing is removed from KycSumSubStatus—a relay-approved / vendor-pending combo no longer blocks the SDK. completed is no longer treated as success (only approved).

API validation tightens finalStatus to an enum and adds optional id on status responses for resume. Docs, changelog, exports, and tests cover hydration, reset races, and reuse paths.

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

[cursor]

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

^{❌ 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 be070de. Configure here.}

[cursor]

Session reuse ignores vendor boundary

High Severity

When a sessionId is already on state, initialize skips the vendor-specific latest-session lookup and can finish at done from a persisted approved sessionStatus for a different vendor. sessionId is not vendor-scoped and activeVendor is not persisted. #createUkycSession also reuses that sessionId when the requested vendor has no session, so a MoonPay session can be attached to an Iron flow.

Additional Locations (1)

• packages/kyc-controller/src/KycController.ts#L1904-L1912

 

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