feat: add ShariboSDK facade so callers stop threading client #284

[midenotch]

Overview

This PR adds an ShariboSDK facade to @sharibo/client so callers stop threading an untyped client through every contract call. Network config, signer, and retry policy are bound once at construction instead of being invisible at the call site. It also repairs the client package (facade-first typecheck + tests), the unparseable scripts/e2e.ts, and completes the app's half-migrated SDK adoption — then locks the boundary in an ADR.

Related Issue

Closes #284

Changes

🧱 ShariboSDK facade

• [ADD] packages/client/src/sdk.ts
  • ShariboSDK.connect(config, keypairOrSigner, options?) resolves the signer, builds the client, and returns an instance holding networkConfig, signer, and retry policy.
  • Instance methods: createCircle, fund, claim, getCircle, getCircleCount, getStatus (alias), hasClaimed.
  • The facade only wraps contract interaction — proving/identity stay stateless free functions.
• [MODIFY] packages/client/src/index.ts — export the facade, keep explorerTxUrl.

🩹 Client package repair

• [ADD] packages/client/src/retry.ts — RetryPolicy, DEFAULT_RETRY_POLICY (maxRetries 3, baseDelayMs 500), withRetry (exponential backoff + jitter; never retries after submission).
• [MODIFY] packages/client/src/contract.ts — annotate all withRetry call sites (ContractTx) so the runtime-any contract client no longer breaks tsc --noEmit.
• [MODIFY] packages/client/src/artifacts.ts — drop module-load side effects (no auto-prefetch / indicator install on import; callers call prefetchMembershipArtifacts() explicitly).
• [MODIFY] client tests — migrate node:test imports to vitest.

🛠️ Script adoption

• [MODIFY] scripts/e2e.ts — rewrite on ShariboSDK.connect per signer (admin + members); no client threaded anywhere; restored parseable control flow; keeps --skip-replay / --reuse-circle / --verbose.
• [MODIFY] scripts/smoke.ts — adopt ShariboSDK.

🎨 App adoption

• [MODIFY] app/src/App.tsx, app/src/hooks/useCircleFlow.ts, app/src/config.ts — everything through ShariboSDK; NETWORK/TOKEN exports, EnvSetupScreen, NetworkBanner.
• [MODIFY] app/src/components/Stepper.tsx — strings from useI18n.
• [ADD] app/src/i18n.tsx — I18nProvider / useI18n / LanguageSwitcher (replaces the .ts file that contained JSX).

📚 Documentation

• [ADD] docs/adr/003-client-boundary.md — the client-package boundary, facade-first priority ordering, JUMP plan, deprecation rules.
• [MODIFY] packages/client/README.md — facade-first quick start.

Verification Results

packages/client: npx tsc --noEmit && npm test
✅ 5 files, 67/67 tests passed

app: npx tsc --noEmit && npm test
✅ 2 files, 13/13 tests passed

scripts: npx tsc --noEmit
✅ typecheck passed

Acceptance criteria	Status
scripts/e2e.ts no longer passes client as an argument anywhere	✅ grep: only sdk.* calls + facade internals remain
ShariboSDK.connect(config, signer) returns an instance holding client, network config, retry policy	✅
Instance methods createCircle, fund, claim, getCircle, getStatus, hasClaimed	✅
Free functions stay exported for one release	✅
README shows the facade first	✅
ADR 003 decides the boundary	✅

Note: scripts/npm test fails 5/5 on this Windows machine — pre-existing and environmental (npx → ENOENT inside the smoke.test.ts subprocess; no subprocess ever runs). Unrelated to this change.