SEP-12 KYC Field Submission Handler

[Kingsman-99]

Description

Cross-border payment flows mediated by SEP-31 anchors require counterparties to complete KYC via the SEP-12 PUT /customer endpoint before a transfer can proceed. The SDK currently leaves callers to construct and submit these requests manually with no field validation or structured error handling. A SEP-12 handler would abstract the upload of KYC text fields and binary documents, poll for approval status, and surface a typed KycNeedsInfoError when the anchor rejects or requests additional fields.

Technical Context

New module src/sep/sep12.ts with a Sep12Client class. Derives the KYC_SERVER URL from the anchor's TOML file using existing TOML utilities in src/utils/toml.ts. Interfaces KycFields, KycDocument, KycStatus, and KycNeedsInfoError added to src/types.ts. Uses FormData and fetch for multipart document upload. The existing SEP-10 auth interceptor in src/auth/sep10.ts is reused to attach the bearer token automatically.

Acceptance Criteria

• Sep12Client.putCustomer(fields: KycFields, docs?: KycDocument[]) submits text fields and optional binary attachments in a single multipart/form-data PUT request
• Sep12Client.getCustomer(id: string): Promise<KycStatus> returns a typed status object with discriminated union ACCEPTED | PROCESSING | NEEDS_INFO | REJECTED
• When status is NEEDS_INFO, the resolved value includes a missingFields: string[] list derived from the anchor's response body
• The SEP-10 JWT is automatically attached as Authorization: Bearer <token> without callers having to pass it manually
• Tests use a mock anchor HTTP server and cover the full status lifecycle plus the NEEDS_INFO and REJECTED error paths
• All CI checks (npm test, npm run build, ESLint/TypeScript) pass and the branch has no merge conflicts

---

[Olamidepy]

@Olamidepy has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hi Maintainer,

I would love to be assigned to this issue.

I’m a Full-Stack Developer and I also actively explore blockchain development and smart contracts, which has strengthened my problem-solving skills and attention to code quality.

After reviewing the issue, I believe I can contribute effectively and deliver a well-tested solution within the expected standards of the project.

ETA: 6 hours

Thank you for your consideration.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Olamidepy to this issue.

[aliybabsi]

@aliybabsi has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

hello, i would love to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @aliybabsi to this issue.

[echoripplestudio]

@echoripplestudio has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I would like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @echoripplestudio to this issue.

[drips-wave]

Congratulations, @echoripplestudio! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @echoripplestudio: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[drips-wave]

This issue has been completed by @echoripplestudio as part of the Stellar Wave Program's 7th Wave 🥳

😎 @echoripplestudio: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.