docs(api): document client surface and fetching conventions

[yunus-dev-codecrafter]

closes #306

Description

src/shared/api/client.ts exposes 50+ functions but API_INTEGRATION.md did not enumerate them or document the conventions around auth, error handling, AbortSignal, and useOptimisticData pairing. Contributors were hand-rolling fetch calls or duplicating endpoints, bypassing the centralized auth/error handling in apiRequest.

This PR adds a comprehensive reference section to stop that pattern.

Changes

docs/API_INTEGRATION.md (new)

• ApiRequestOptions contract — documents requiresAuth and the spread RequestInit fields (signal, method, body, headers)
• Error handling conventions — table of all 4 error categories (network, 401, 403, other) with thrown messages and getUserFriendlyError mappings, plus the <DataState> display pattern
• AbortSignal convention — maintainer fetchers accept { signal } for useOptimisticData cancellation; generic fallback for other endpoints
• Canonical useOptimisticData pattern — full runnable tsx example based on the real PullRequestsTab/IssuesTab code
• Endpoint reference — 16 grouped tables (auth, profile, projects, ecosystems, leaderboard, billing, maintainers, issue/PR actions, etc.) covering all 50+ functions with HTTP method and auth requirement
• Security notes — VITE_ env vars are public; JWT lives in localStorage under patchwork_jwt (XSS caveat from config/api.ts)
• Deprecations — getProjectIssues/getProjectPRs → getMaintainerIssues/getMaintainerPRs

CONTRIBUTING.md (modified)

• Replaced the verbose "API Client Conventions" section with a cross-link to docs/API_INTEGRATION.md and 5 quick rules

Acceptance Criteria

• Endpoints grouped with method/auth
• Error and AbortSignal conventions documented
• Canonical fetch pattern shown
• Cross-linked from CONTRIBUTING.md

Security Notes

• VITE_ environment variables are compiled into the client bundle and must never hold secrets
• JWT is stored in localStorage (patchwork_jwt), which is XSS-vulnerable; httpOnly cookies recommended for production
• The test suite (client.test.ts) asserts that raw tokens never leak into stdout, console logs, or error strings

How to Review

1. Read docs/API_INTEGRATION.md — verify all endpoint signatures match src/shared/api/client.ts
2. Verify the cross-link in CONTRIBUTING.md:171 points to the new file
3. Run pnpm run format:check (if network permits)

[Jagadeeshftw]

hey @yunus-dev-codecrafter, thanks for jumping in! closing this pr because the author needs to be assigned to the linked issue (#306) before opening a pr. please comment on the issue requesting assignment, wait to be assigned, then re-raise your pr. this keeps work fairly distributed across contributors. hope to see a revised pr from you soon!