Add upstream error fields and public error contract tests

[tolgahan-arikan]

Summary

• add normalized upstreamError details and clearer transaction execution/status error semantics
• add public SDK error contract snapshots and connector provider/wagmi error coverage
• switch connector SDK dependency to workspace:* and document the pnpm release flow
• add docs/error-contracts.md as the audit matrix for public error contracts

Verification

• pnpm --filter @0xsequence/oms-wallet-wagmi-connector test
• pnpm --filter @0xsequence/oms-wallet-wagmi-connector build
• pnpm test
• pnpm check:package-versions
• pnpm build
• pnpm build:wagmi-example

Note: pnpm build:wagmi-example still emits the existing Vite large-chunk warning, but the build succeeds.

[claude]

Claude finished @tolgahan-arikan's task —— View job

---

Pull Request Review

I've conducted a thorough review of this PR that adds upstream error fields and public error contract tests. Here's my comprehensive analysis:

Todo List:

• Read and analyze core error handling changes
• Review new error contract tests for completeness
• Check public API changes in API.md and type-tests
• Verify import patterns and TypeScript soundness
• Check for any committed secrets or credentials
• Provide comprehensive review feedback

---

Review Summary

This is an excellent PR that significantly improves error handling and testing coverage in the OMS TypeScript SDK. The implementation is well-designed, thoroughly tested, and properly documented.

✅ Strong Points

1. Well-Designed Error Enhancement

• OmsUpstreamError interface: Clean design with appropriate service differentiation (waas | indexer)
• Normalized error mapping: upstreamErrorFromError function properly extracts and normalizes diagnostic information
• Backward compatibility: All existing error classes remain unchanged, new field is optional

2. Comprehensive Test Coverage

• 1683 lines of error contract tests covering all failure scenarios
• Proper service differentiation: Tests verify service: "waas" vs service: "indexer" correctly
• Snapshot-based validation: Ensures stable public error contracts
• Good coverage matrix: Both upstream and local errors properly tested

3. Excellent Documentation

• docs/error-contracts.md: Outstanding audit matrix documenting every error scenario
• API.md updates: Proper documentation of new upstreamError field and its purpose
• Type definitions: Well-documented with clear usage guidance

4. Proper Implementation Patterns

• Service-specific error creation: indexerRequestFailure() and indexerResponseError() properly set service: "indexer"
• WaaS errors: Correctly use service: "waas" in toOmsSdkError()
• Connector error preservation: createTransactionExecutionError() test shows SDK errors properly preserved through wagmi wrapper

5. Technical Correctness

• Import patterns: All relative imports in src/ use proper .js extensions ✅
• TypeScript soundness: Error types are well-defined with appropriate optional fields ✅
• No secrets committed: Clean of any credential values ✅
• Package versioning: Correctly uses workspace:* for connector SDK dependency ✅

📝 Minor Observations

1. Connector Error Propagation (informational)

The connector tests in omsWalletConnector.test.ts:320-340 correctly show SDK errors preserved through wagmi wrapping:

expect(error.data).toMatchObject({
  name: "OmsTransactionError",
  upstreamError: {
    service: "waas",
    name: "WebrpcRequestFailed"
  }
})

This is exactly the right approach for maintaining error context through provider boundaries.

2. Error Contract Matrix Alignment

The test coverage perfectly aligns with the error contract matrix in docs/error-contracts.md. Every scenario from the matrix has corresponding test coverage with proper upstream error presence/absence.

🎯 Key Implementation Highlights

Error Mapping Logic (src/errors.ts:212-231)

function upstreamErrorFromError(
    error: unknown,
    service: OmsUpstreamError["service"],
): OmsUpstreamError | undefined

This function properly handles the decision logic for when upstream errors should be present vs absent, which is critical for the public error contract.

Service Differentiation (src/clients/indexerClient.ts:177)

upstreamError: indexerRequestFailure(error),  // service: "indexer"

vs src/clients/walletClient.ts:27

throw toOmsSdkError(error, operation);  // service: "waas" (default)

Perfect separation of concerns between services.

Test Coverage Validation

The error contract tests comprehensively validate:

• ✅ WaaS transport/domain/HTTP errors with upstream details
• ✅ Local validation/session/OIDC errors without upstream details
• ✅ Indexer backend/transport errors with upstream details
• ✅ Connector error preservation through wagmi wrapping

🏆 Overall Assessment

This PR represents high-quality engineering work that:

• Enhances error diagnostics without breaking existing behavior
• Provides comprehensive test coverage with proper contracts
• Includes excellent documentation and error matrices
• Follows all repository conventions and patterns

Recommendation: ✅ APPROVE

The implementation is correct, well-tested, and ready for merge. The error contracts are properly documented and the test coverage ensures the behavior is locked in for the future.