Add strict API envelope mode docs to engage-native

repositories/d-sports-engage-native.mdx

@@ -1,12 +1,12 @@
 ---
 title: "d-sports-engage-native"
 description: "Native iOS and Android app for D-Sports Engage. Expo 54, React Native, Clerk, RevenueCat, Thirdweb."
 icon: "smartphone"
 ---
 
 ## Overview
 
 **d-sports-engage-native** (package name: `engage-native`) is the native mobile app for D-Sports. It mirrors the core PWA experience on iOS and Android: wallet, shop, leaderboard, locker room, and profile.
 
 - **Run:** `bunx expo start` or `bun run start` — then press `a` for Android or `i` for iOS, or scan the QR code with Expo Go.
 
@@ -17,18 +17,18 @@
 | Framework  | Expo 54, React Native 0.81, React 19 |
 | Auth       | Clerk (Expo)              |
 | Payments   | RevenueCat (react-native-purchases) |
 | Web3       | Thirdweb                  |
 | State      | Zustand                   |
 | Storage    | MMKV                      |
 | UI         | Lucide React Native       |
 | Navigation | Expo Router               |
 | Package    | Bun                       |
 
 ## Features
 
 - **Wallet** — Tokens, holdings, pack opening, crypto checkout (via PWA backend)
 - **Shop** — Collectibles, cart, coin bundles, checkout
 - **Leaderboard** — Rankings and filters
 - **Locker room** — Social feed and engagement
 - **Profile** — User profile and settings
 - **Theme** — Dark/light mode (default dark)
@@ -36,12 +36,70 @@
 ## Getting started
 
 1. Clone the repository and run `bun install`.
 2. Configure environment (Clerk, RevenueCat, Thirdweb, API base URL) per repo README.
 3. Run `bunx expo start`.
 4. For development builds: `bun run build:dev` (EAS) or run with Expo dev client.
 
 The app targets both native and web (responsive) and uses the same backend (d-sports-api) as the PWA for API and checkout flows.
 
+## API client
+
+The native app communicates with `d-sports-api` through a typed client layer in `lib/api/`. The `useApi()` hook exposes domain-specific modules (wallet, shop, user, quests, leaderboard, locker room, teams, collectibles, checkout) with automatic Clerk token injection.
+
+### Strict envelope mode
+
+The API client (`lib/api/client.ts`) operates in **strict envelope mode**. Every successful API response must conform to the normalized envelope:
+
+```json
+{
+  "success": true,
+  "data": { ... }
+}
+```
+
+Error responses follow the same shape:
+
+```json
+{
+  "success": false,
+  "error": "Human-readable message",
+  "code": "MACHINE_READABLE_CODE"
+}
+```
+
+If a response does not include a top-level `success` field, the client rejects it with an `INVALID_RESPONSE_ENVELOPE` error code. There is no fallback parsing for legacy response shapes.
+
+<Warning>
+  All backend routes consumed by the native app **must** return the `{ success, data?, error?, code? }` envelope. Routes that return raw objects or arrays will cause client-side failures.
+</Warning>
+
+### API modules
+
+| Module | Import | Covers |
+| --- | --- | --- |
+| User | `createUserApi` | Profile, preferences, team membership |
+| Wallet | `createWalletApi` | Tokens, holdings, transactions |
+| Shop | `createShopApi` | Products, collectibles |
+| Checkout | `createCheckoutApi` | Crypto and fiat checkout flows |
+| Quests | `createQuestsApi` | Daily quests and rewards |
+| Leaderboard | `createLeaderboardApi` | Rankings and filters |
+| Locker room | `createLockerRoomApi` | Social feed and posts |
+| Teams | `createTeamsApi` | Team data and membership |
+| Collectibles | `createCollectiblesApi` | Owned packs and items |
+
+## Environment variables
+
+The app uses `EXPO_PUBLIC_*` variables accessible at runtime:
+
+| Variable | Purpose |
+| --- | --- |
+| `EXPO_PUBLIC_API_URL` | Backend API base URL (defaults to `https://api.d-sports.org`) |
+| `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY` | Clerk authentication |
+| `EXPO_PUBLIC_TW_CLIENT_ID` | Thirdweb Web3 client |
+| `EXPO_PUBLIC_REVENUECAT_API_KEY` | RevenueCat in-app purchases |
+| `EXPO_PUBLIC_SUPABASE_URL` | Supabase client URL |
+| `EXPO_PUBLIC_SUPABASE_KEY` | Supabase publishable key |
+
 <Card title="Ecosystem overview" icon="map" href="/repositories/ecosystem-overview">
   See how the native app fits with the PWA, site, and Mic'd Up.
 </Card>