test(api): client envelope/refresh/error tests; docs: README; fix: synchronous single-flight refresh reset

src/api/client.ts

@@ -61,15 +61,15 @@ async function tryRefresh(): Promise<boolean> {
       return true
     } catch {
       return false
-    } finally {
-      // allow the next expiry to trigger a fresh attempt
-      setTimeout(() => {
-        refreshInFlight = null
-      }, 0)
     }
   })()
 
-  return refreshInFlight
+  try {
+    return await refreshInFlight
+  } finally {
+    // reset once settled so the next expiry triggers a fresh attempt
+    refreshInFlight = null
+  }
 }
 
 async function parseError(res: Response): Promise<ApiError> {