feat: sponsorship error type and fallback

[0xsisyfos]

Sponsorship error type and user_pays fallback

Summary

Adds SDK error when sponsored (gasless) execution is unavailable and optional automatic fallback to user-paid fees. AVNU and Cartridge errors are normalized to a single contract so apps can show consistent UX.

New public API

• SponsorshipNotAvailableError – Error with reason, provider ("avnu" | "cartridge" | "unknown"), fallbackFeeRequired: true, rawError
• Normalized reasons: policy_rejected, policy_exceeded, unsupported_asset, invalid_paymaster_config, network_unavailable, account_not_ready, unknown
• DevX: SponsorshipNotAvailableError.isSponsorshipError(e), toFriendlyMessage(), getSponsorshipFriendlyMessage(reason), SPONSORSHIP_REASONS, SPONSORSHIP_REASON_MESSAGES
• Subpath: starkzap/sponsorship for a focused import

ExecuteOptions

• fallbackTo?: "user_pays" – On sponsorship failure, retry with user-paid fees
• onFallback?: (error: SponsorshipNotAvailableError) => void – Called before retry (e.g. toast)

Behavior

• Signer + Cartridge wallets: Try sponsored execution; on failure, normalize (AVNU or Cartridge). If sponsorship error and fallbackTo === "user_pays", ensure account is deployed, call onFallback, then retry with user_pays. Non-sponsorship errors are rethrown unchanged
• Fallback preconditions: If fallback requested but account not deployed, throw SponsorshipNotAvailableError with reason: "account_not_ready"
• Scope: Only failures that clearly mean “sponsorship unavailable” are normalized; contract reverts are not converted

Internal

• src/wallet/sponsorship-errors.ts – normalizeAvnuSponsorshipError() and normalizeCartridgeSponsorshipError() (config/auth → invalid_paymaster_config, quota → policy_exceeded, etc.)

Files changed

• src/types/sponsorship-error.ts (new)
• src/types/wallet.ts (ExecuteOptions + type import)
• src/types/index.ts (export)
• src/wallet/sponsorship-errors.ts (new)
• src/wallet/index.ts (fallback + runSponsoredExecution)
• src/wallet/cartridge.ts (fallback)
• src/sponsorship.ts (new)
• package.json (exports ./sponsorship)

Breaking changes

None. Additive only.