api-sync prompt: structural rule + auto-fix lint order

Folds in the same two lessons from blindpay-node #51:

1. Nested API endpoints become methods on the existing resource class,
   not new files / new resource classes. Added a 'Decide: new resource,
   or method on an existing one?' section in CLAUDE.md (section 3)
   with the RFI worked example, and a corresponding step in the
   workflow prompt.

   PR #46 created src/blindpay/resources/receivers/rfi.py with its
   own RfiResource class for two endpoints. The existing pattern for
   nested-under-receivers endpoints (get_limits,
   get_limit_increase_requests, request_limit_increase) is direct
   methods on ReceiversResource. New rule pins that.

2. The lint step in the prompt now runs the auto-fix forms (ruff
   format, ruff check --fix) BEFORE the validate forms. Same lesson
   as #51 in the Node SDK — running only the read-only check leaves
   formatter diffs unresolved.

3. Step also reminds the agent to grep for fixtures of any type
   that gains a new required field, otherwise type-check will fail
   somewhere far from the original edit.

Author: alvseven

.github/workflows/api-sync.yml

@@ -62,15 +62,41 @@ jobs:
             INSTRUCTIONS:
             1. Read CLAUDE.md thoroughly for this SDK's patterns and conventions.
             2. Read /tmp/api-sync/changelog.md — it lists every enum type with every value, every field to add, and every change to make.
-            3. Implement ALL changes. Go through the changelog section by section:
+            3. Before implementing any new endpoint, decide where it
+               lives. Read the "Decide: new resource, or method on an
+               existing one?" section in CLAUDE.md (section 3). For
+               each new endpoint:
+                 a. Find sibling endpoints — other endpoints whose URL
+                    path shares a prefix (e.g. POST /receivers/{id}/rfi
+                    is a sibling of /receivers/{id}/limit-increase).
+                 b. Match how those siblings are modeled. If they are
+                    direct methods on an existing resource class (e.g.
+                    receivers.get_limit_increase_requests), add the
+                    new endpoint as a method on the SAME class.
+                 c. Do NOT create a new RfiResource class or a new
+                    file under receivers/rfi.py for 1–3 child
+                    endpoints. Do NOT put a child of an existing
+                    resource at the top level of src/blindpay/resources/.
+                 d. After adding a required field to an existing
+                    TypedDict, grep the repo for fixtures and
+                    constructors of that type and add the field to
+                    each. mypy/pyright will fail otherwise.
+            4. Implement ALL changes. Go through the changelog section by section:
                - Section 1 (Enum Types): For each enum listed, check if the SDK has it. If missing, create it. If it exists, add any missing values. The changelog lists ALL values — add the ones that don't exist yet.
                - Section 2 (Receiver Fields): Add each listed field to the receiver input/output types.
                - Section 3 (Version): Minor bump.
-            4. Do not skip ANY enum or field. Every item in the changelog must be addressed.
-            5. Follow CLAUDE.md patterns exactly for naming, typing, and file organization.
-            6. MINOR version bump only.
-            7. Run lint and type check commands (see CLAUDE.md). Fix any errors until clean.
-            8. Do NOT create commits — just modify the files.
+            5. Do not skip ANY enum or field. Every item in the changelog must be addressed.
+            6. Follow CLAUDE.md patterns exactly for naming, typing, and file organization.
+            7. MINOR version bump only.
+            8. Run, in this order:
+                 ruff format src/         # auto-format
+                 ruff check src/ --fix    # auto-fix lint issues
+                 ruff check src/          # validate (must report 0 errors)
+                 mypy src/                # type-check
+               Fix any errors until all four are clean. Running only
+               the check forms surfaces formatter diffs as failures —
+               always run the auto-fix forms first.
+            9. Do NOT create commits — just modify the files.
 
       - name: Commit and push
         id: commit

CLAUDE.md

@@ -114,7 +114,54 @@ Resource-specific Literal types and TypedDicts are defined in the same file as t
 
 ---
 
-## 3. How to add a new resource
+## 3. Decide: new resource, or method on an existing one?
+
+Before adding files, decide whether a new endpoint deserves its own
+resource directory and class pair, or whether it belongs as a method
+on an existing one. Default to the second — methods on an existing
+resource are the right choice for most new endpoints.
+
+**Look at sibling endpoints first.** Find other endpoints whose URL
+path shares a prefix with the new one (e.g. `POST /receivers/{id}/rfi`
+is a sibling of `GET /receivers/{id}/limit-increase`, which is
+modeled as `client.receivers.get_limit_increase_requests(id)`, not as
+`client.receivers.limit_increase.list()`). Match how those siblings
+are modeled.
+
+**Heuristics:**
+
+- 1–3 endpoints under an existing parent path → add as direct methods
+  on the parent's resource class. Naming: `<verb>_<subresource>` —
+  e.g. `client.receivers.get_rfi(receiver_id)` and
+  `client.receivers.submit_rfi(receiver_id=..., data=...)`. **Do not**
+  create a new `Rfi`/`RfiResource` class or a new file under
+  `src/blindpay/resources/receivers/rfi.py`.
+- 4+ endpoints with a distinct ID space, or a clearly separate
+  conceptual resource (`bank_accounts`, `blockchain_wallets`,
+  `virtual_accounts`) → its own directory + class pair, wired under
+  the parent via the namespace pattern (Section 7). Confirm there is
+  precedent in the existing codebase before doing this.
+- Never put a child of an existing resource at the **top level** of
+  `src/blindpay/resources/` (e.g. `src/blindpay/resources/rfi/`). If
+  it's nested in the API URL, it's nested in the SDK.
+
+### Worked example: RFI
+
+`GET /receivers/{id}/rfi` and `POST /receivers/{id}/rfi` are two
+endpoints nested under `receivers`. Add them as methods on
+`ReceiversResource` / `ReceiversResourceSync` in
+`src/blindpay/resources/receivers/receivers.py`, alongside
+`get_limits`, `get_limit_increase_requests`, and
+`request_limit_increase`. NOT as a new `RfiResource` class in
+`receivers/rfi.py`.
+
+---
+
+## 4. How to add a new resource
+
+(Use this section only when the heuristics above say the endpoint is
+a genuinely new top-level resource — not just a 1–3-endpoint
+extension of an existing one.)
 
 ### Step 1: Create the resource directory and files