[codex] Expose settlement recovery state

[senamakel-droid]

Summary

• add typed SDK recovery metadata for Solana transactions that confirm before backend settlement fails
• attach settlement_failed_after_execution with the on-chain tx, payment map, settlement request, and retry/refund flags to the thrown error
• cover the failed settlement path with a swap-referenced payment regression test

Validation

• ./node_modules/.bin/vitest run tests/payments.test.ts
• ./node_modules/.bin/tsc --noEmit
• ./node_modules/.bin/tsc

Summary by CodeRabbit

• New Features
  • Enhanced Solana payment settlement with recovery capabilities—now provides retry or refund options when settlement fails after execution
  • Added detailed error recovery metadata including on-chain transaction signatures and execution details for improved troubleshooting and transparency

[vercel]

@senamakel-droid must be a member of the Vezures team on Vercel to deploy.
- Click here to add @senamakel-droid to the team.
- If you initiated this build, request access.
- If you're already a member of the Vezures team, make sure that your Vercel account is connected to your GitHub account.

Learn more about collaboration on Vercel and other options here.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 0babd546-6bd6-4081-bea5-9ffc6d049805

📥 Commits

Reviewing files that changed from the base of the PR and between fe5642f and ae5651e.

📒 Files selected for processing (3)

• sdk/typescript/src/api/payments.ts
• sdk/typescript/src/index.ts
• sdk/typescript/tests/payments.test.ts

---

📝 Walkthrough

Walkthrough

New exported types SolanaSettlementRecoveryState, SolanaSettlementRecovery, and SolanaSettlementFailure are added to the payments module. settleWithSolanaPayment is updated to catch settlement errors and enrich them with recovery metadata via a new attachSolanaSettlementRecovery helper. The types are re-exported from the barrel, and a new test covers the failure path.

Changes

Solana Settlement Failure Recovery

Layer / File(s)	Summary
Recovery types, settleWithSolanaPayment error enrichment, and attachSolanaSettlementRecovery helper sdk/typescript/src/api/payments.ts	Defines SolanaSettlementRecoveryState, SolanaSettlementRecovery, and SolanaSettlementFailure interfaces. Refactors settleWithSolanaPayment to wrap settle() in a try/catch that calls attachSolanaSettlementRecovery before rethrowing. attachSolanaSettlementRecovery mutates the thrown object in-place with execution, onChainTx, payment, and a fully-populated settlementRecovery payload including retryable and refundRequired flags.
Barrel re-exports and settlement failure test sdk/typescript/src/index.ts, sdk/typescript/tests/payments.test.ts	Extends the ./api/payments.js type export list with the three new types. Adds a Vitest test that mocks Solana RPC calls, forces a 500 on payments/settle, and asserts the SDK throws a TinyPlaceError with the expected SolanaSettlementFailure shape, including settlementRecovery state, retry/refund flags, onChainTx, execution.signature, and the correct settlement request fields.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hop, hop — the transaction flew,
But the settle call went askew!
Now errors carry a map and a key,
"retry_settlement_or_refund" — whee!
Recovery state wrapped tight as a bow,
No lost coins on the blockchain, oh!
✨ The rabbit audits every throw.

---

Note

🎁 Summarized by CodeRabbit Free

The PR author is not assigned a seat. To perform a comprehensive line-by-line review, please assign a seat to the pull request author through the subscription management page by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ae5651eb15

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Set retryable only for transient settlement failures

When /payments/settle returns a non-retryable client error after the Solana transfer has already confirmed, such as an expired authorization or invalid signature, this recovery object still advertises retryable: true for the same settlementRequest. Callers using the new recovery state can then keep retrying a request the backend will deterministically reject instead of moving directly to refund/regeneration logic; the flag should account for the thrown TinyPlaceError.status/body or avoid claiming retryability for all failures.

Useful? React with 👍 / 👎.