feat: add structured GuildPassErrorCode to BatchItemResult error entries

[mr-abims]

Description

Adds code: GuildPassErrorCode to every { status: 'error' } entry in BatchItemResult[] (from batchEthCall, getMembershipTokenBalancesBatch, getGuildOwnersBatch), so callers can branch on failure type per item instead of string-matching. Codes are consistent across all three batch strategies: revert → HTTP_ERROR, unusable response → INVALID_RESPONSE, quorum failure → CONSENSUS_MISMATCH. All error strings are unchanged; the type change is purely additive.

Also fixes a latent bug found along the way: WS_CONNECTION_ERROR was referenced in webSocketProvider.ts but never declared on the enum, so WS errors carried code: undefined.

Semver impact: minor

Linked Issue

Closes #390

Type of Change

• 🐛 Bug fix (patch)
• ✨ New feature / method (minor)
• 💥 Breaking change (major)
• 📝 Documentation / TypeDoc update
• 🔧 Chore / refactor
• 🧪 Tests only

Changes Made

• src/contracts/contract.types.ts — add optional code to BatchItemResult
• src/contracts/batchErrors.ts, src/errors/toErrorCode.ts (new) — error-entry constructor, code extraction, and normalisation of third-party provider results (fallback UNKNOWN_ERROR)
• src/contracts/contractClient.ts, providers/*, adapters/* — attach codes on every per-item failure path; three sites that swallowed the caught error's code now propagate it
• src/errors/errorCodes.ts — declare missing WS_CONNECTION_ERROR
• tests/batch-item-error-codes.test.ts, tests/error-code-integrity.test.ts (new) + updated batch test assertions
• docs/api-reference.md — BatchItemResult section with code table and branching example; CHANGELOG.md; regenerated api-report

Public API Changes

type BatchItemResult = {
  status: 'success' | 'error';
  result?: string;
  error?: string;
  code?: GuildPassErrorCode; // NEW — always set on error entries from the batch methods
};

GuildPassErrorCode.WS_CONNECTION_ERROR = 'WS_CONNECTION_ERROR' // new member

Test Evidence

pnpm test:run output:

Build Evidence

pnpm build output:

Checklist

• I have read CONTRIBUTING.md
• This PR is linked to an open issue
• pnpm typecheck passes
• pnpm lint passes
• pnpm test:run passes — all tests green
• pnpm build succeeds — dist/ generated cleanly
• All new public methods/types have TypeDoc comments
• New behaviour is covered by at least one Vitest unit test
• No new runtime dependencies added without prior maintainer approval
• docs/ updated if public API changed
• examples/ updated if new usage patterns were added
• Backwards compatibility maintained (or breaking change clearly noted above)

Additional Notes

[Lakes41]

This PR cannot be merged automatically because it has merge conflicts and one or more workflow checks failed.

Please update the branch with the latest base branch, resolve the conflicts, and fix the failing workflow checks.

After the conflicts are resolved and checks pass, the automation can review it again.

[Lakes41]

This PR cannot be merged automatically because one or more workflow checks failed.

Please review the failed checks, push a fix, and wait for the workflows to pass.

After the checks pass and there are no merge conflicts, the automation can review it again.

[Lakes41]

This PR cannot be merged automatically because it has merge conflicts and one or more workflow checks failed.

Please update the branch with the latest base branch, resolve the conflicts, and fix the failing workflow checks.

After the conflicts are resolved and checks pass, the automation can review it again.