fix(ci): clear mypy gate — types-requests stubs + latent create_folder bug

The 2026-05-29 issues-fixes commit broke the CI mypy step (10 errors):

- Add types-requests to requirements-dev.txt (7 missing-stub errors)
- Fix copy_folder calling create_folder with a dict instead of
  (name, parent_folder_uuid, ...); update the masking test mock
- Annotate all_items: list in cli.py
- restore_item destination_folder_uuid: str -> Optional[str]

All gates green: ruff, mypy, bandit, 591 unit + 31 live tests pass.
Docs (HISTORY/LEARNINGS/readme) updated.

Author: CrispStrobe

HISTORY.md

@@ -6,6 +6,33 @@ retrospective lessons see [`LEARNINGS.md`](LEARNINGS.md).
 
 ---
 
+## CI mypy-gate fix (2026-05-30)
+
+The 2026-05-29 issues-fixes commit (`f5bf51c`) was green locally but the CI
+**Type check (mypy)** step fast-failed (24s) with 10 errors. The earlier
+local runs hadn't caught them because of a split toolchain (homebrew mypy /
+conda python / framework pip) where the freshly-installed stubs landed in a
+different interpreter than the one mypy actually used. Fixes:
+
+- **`types-requests` missing.** mypy reported "Library stubs not installed
+  for requests" at 7 sites. Added `types-requests>=2.31.0` to
+  `requirements-dev.txt`. CI installs everything into one venv, so the
+  requirements line is sufficient there.
+- **Latent `create_folder` signature bug.** `copy_folder` (`drive.py`) called
+  `self.create_folder(payload_dict)`, but `DriveService.create_folder` takes
+  `(name, parent_folder_uuid, ...)` — the dict was being passed as `name`.
+  The unit test masked it with a `fake_create(payload)` mock, so only mypy's
+  `arg-type` error flagged it. Fixed the call to pass named args and updated
+  the test mock to match the real signature.
+- **Two minor type errors:** annotated `all_items: list` in `cli.py` and
+  changed `restore_item`'s `destination_folder_uuid: str = None` to
+  `Optional[str]` in `utils/api.py`.
+
+All four gates (ruff, mypy, bandit, pytest) pass again. Test count:
+**591 unit + 31 live = 622**, re-verified against live credentials.
+
+---
+
 ## GitHub Issues Fixes + Feature Work (2026-05-29)
 
 Two rounds of work addressing all 6 open GitHub issues plus feature

LEARNINGS.md

@@ -60,6 +60,19 @@ backend does. Integration tests verify what the backend actually
 does.** Both are needed. Unit tests for fast iteration on code logic;
 live tests as a contract check.
 
+### A mock can hide a real signature mismatch — mypy won't
+
+`copy_folder` called `self.create_folder(payload_dict)` while the real
+`DriveService.create_folder(name, parent_folder_uuid, ...)` expects a
+string. The test passed for months because its `fake_create(payload)`
+mock accepted exactly the wrong shape the production code was sending —
+the mock was written against the bug, not against the signature. mypy's
+`arg-type` error was the only thing that caught it. Lesson: **when a test
+mocks a method, mock its real signature, not the call site you happen to
+have.** And keep the type gate green in CI, not just locally — a split
+toolchain (mypy and pip pointing at different interpreters) silently
+masked it on the dev machine.
+
 ---
 
 ## On the trust roots

cli.py

@@ -2016,7 +2016,7 @@ def trash_list(item_type: str, limit: int, as_json: bool):
         auth_service.get_auth_details()
 
         offset = 0
-        all_items = []
+        all_items: list = []
         while True:
             page_size = min(limit - len(all_items), 50)
             result = api_client.get_trash_content(offset=offset, limit=page_size,

readme.md

@@ -270,7 +270,7 @@ internxt-python/
 │   └── webdav_server.py      # WebDAV server management
 ├── utils/
 │   └── api.py                # HTTP API client
-├── tests/                    # Pytest suite (~560 tests, 90% coverage)
+├── tests/                    # Pytest suite (622 tests, 90% coverage)
 ├── pyproject.toml            # Pytest, coverage, ruff config
 ├── requirements-dev.txt      # Dev/test dependencies
 └── .github/workflows/ci.yml  # Lint + type-check + test on Py 3.10/3.11/3.12
@@ -294,7 +294,8 @@ pip install -r requirements-dev.txt
 
 ### Running Tests
 
-The project ships with a 557-test pytest suite at **90% line coverage**.
+The project ships with a 591-test unit suite at **90% line coverage**
+(plus 31 optional live tests — 622 total).
 It covers crypto round-trips, path resolution, upload/download conflict
 handling, the WebDAV provider, all major CLI commands, and a real
 encrypt → upload → "wire" → download → decrypt round-trip cycle.
@@ -337,7 +338,7 @@ Per-module coverage:
 
 #### Live integration smoke (optional)
 
-`tests/test_live_smoke.py` is a 22-test suite that runs end-to-end
+`tests/test_live_smoke.py` is a 31-test suite that runs end-to-end
 against the real Internxt backend, covering: login, list, upload (small
 + unicode + extensionless + 2 MB), download with byte-for-byte
 verification, recursive folder creation, file rename/move/copy/update,

requirements-dev.txt

@@ -4,6 +4,7 @@ pytest>=7.4.0
 pytest-cov>=4.1.0
 ruff>=0.1.0
 mypy>=1.5.0
+types-requests>=2.31.0
 bandit>=1.7.0
 
 # Optional: load IXT_ACCOUNT/IXT_PWD from .env for the live smoke test

services/drive.py

@@ -746,16 +746,12 @@ def copy_folder(self, source_folder_uuid: str, destination_parent_uuid: str,
         modification_time = source_meta.get('modificationTime') or source_meta.get('updatedAt')
 
         # Create destination folder
-        payload: Dict[str, Any] = {
-            'plainName': name,
-            'parentFolderUuid': destination_parent_uuid,
-        }
-        if creation_time:
-            payload['creationTime'] = creation_time
-        if modification_time:
-            payload['modificationTime'] = modification_time
-
-        new_folder = self.create_folder(payload)
+        new_folder = self.create_folder(
+            name,
+            destination_parent_uuid,
+            creation_time=creation_time,
+            modification_time=modification_time,
+        )
         new_folder_uuid = new_folder['uuid']
         print(f"     📁 Created folder: {name} → {new_folder_uuid}")
 

tests/test_drive_misc.py

@@ -246,9 +246,10 @@ def fake_get_meta(uuid):
         call_count['get_folder_metadata'] += 1
         return fake_folder_meta if uuid == 'src-uuid' else fake_sub_meta
 
-    def fake_create(payload):
+    def fake_create(name, parent_folder_uuid=None, creation_time=None,
+                    modification_time=None):
         call_count['create_folder'] += 1
-        if payload['plainName'] == 'Src':
+        if name == 'Src':
             return fake_new_folder
         return fake_sub_folder
 

utils/api.py

@@ -351,7 +351,7 @@ def clear_trash(self) -> Dict[str, Any]:
         url = f"{self.drive_api_url}/storage/trash/all"
         return self.delete(url)
 
-    def restore_item(self, item_uuid: str, item_type: str, destination_folder_uuid: str = None) -> Dict[str, Any]:
+    def restore_item(self, item_uuid: str, item_type: str, destination_folder_uuid: Optional[str] = None) -> Dict[str, Any]:
         """
         Restore item from trash - keeping original implementation
         (Not clearly shown in provided SDK snippets)