mobile-api — Canonical Skill

Purpose

Keep all HTTP traffic on the useApi() fetch client with correct auth, error, and networking semantics.

When to use

New/changed endpoints, interceptors, timeout/retry, pagination, DTOs, upload/download progress, offline/timeout handling.

Required reading

• skills/mobile/API.md
• docs/agent/API_INTEGRATION_CONTRACT.md

Relevant project locations

• src/composables/useApi.ts, src/api/*Service.ts
• .env* (keys only — never copy values)

Mandatory rules

1. Use only useApi(); never add another client (axios was removed) or weaken TLS.
2. Never invent contracts — classify VERIFIED_FRONTEND_USAGE vs UNVERIFIED_BACKEND_ASSUMPTION; backend repo is out of scope.
3. Respect status ≥ 400 → ApiFetchError, json-bigint, and the shared 401 refresh. Only a 403 from refresh removes auth; ordinary 403 rejects.
4. localhost in-app ≠ dev machine — use env base URLs; verify per platform.
5. IDs in responses/params are snowflake strings (json-bigint storeAsString); type them IdType, never convert to numbers.
6. api.raw still throws on status ≥ 400 — catch ApiFetchError (or check error.status) where a page needs 4xx bodies; wrap loading UI in try/finally.

Implementation workflow

1. Confirm endpoint path/method/DTO and base URL against frontend usage; pass baseURL per call (CDN: VITE_CDN_BASE_URL, absolute URL: '').
2. Call useApi() directly or add a service method — choose per skills/mobile/API.md §2 (no src/api file required for single-use endpoints); add error/loading states; avoid duplicate submits.
3. Handle timeout/offline/cancel paths explicitly.
4. Verify per mobile-testing (mocked API tests; device for real network).

Verification

API-contract check (method/path/DTO), error-path tests; no invented backend behavior.