feat(types): fix pagination cursor, billing fee, account type and wallet-create types

[ericviana]

Summary

Fixes four type-surface defects surfaced by .api-sync/sync.py --audit-types (added in #58) and a follow-up manual review. These are type-surface changes for existing consumers, not new API surface -- in every case the wire contract already behaved this way; the SDK's declared type was simply wrong, and this PR makes the type match the (unchanged) reality. Anyone relying on the old, incorrect type is the one currently at risk (a str-typed field that was always secretly a number, an int-typed field that was always secretly a nullable id string, an enum value the API has never accepted), not the other way around.

The four fixes, quoting the contract for each

1. PaginationMetadata.next_page / .prev_page: int -> Optional[str]

Contract (packages/api-contract/src/generic.schema.ts): next_page: z.string().nullish(), example "pi_123". It's a pagination cursor id, not a page number. This is the same defect that makes the go/php/swift SDKs throw at runtime on any paginated list call; TypedDicts aren't runtime-enforced, so python silently accepted whatever the wire sent -- the declared type was just misleading every typed consumer (autocomplete, mypy/pyright checks on their own code) into treating it as an integer.

2. Payin.billing_fee_amount: Optional[str] -> Optional[float]

Spec: {"type": ["number", "null"], "description": "Billing fee in cents...", "example": 50}. Every other monetary _amount/_fee field in this SDK is float -- including Payout.billing_fee_amount, already correct. Payin.billing_fee_amount was the one outlier.

Chose Optional[float], matching the repo's own established, universal convention for monetary fields (verified: every _amount/_fee response field across quotes.py, payins/quotes.py, payins.py, transfers.py, payouts.py is float; none use int or str for money). No competing convention exists to override this.

Also added billing_fee_amount: NotRequired[Optional[float]] to GetPayinTrackResponse and CreateEvmPayinResponse. Correction to my own prior work: these map to the same wire schemas as Payin (PayinOut/CreatePayinOut respectively, both of which have this field), but did not model it at all before this PR -- not "modeled with the wrong type," simply absent. The .api-sync/unmodeled.json entry I wrote in #58 for CreatePayinOut.billing_fee_amount incorrectly asserted "Payin/GetPayinTrackResponse do model it"; only Payin did. Fixed now, correctly typed from the start, on all three.

3. BankAccountType: Literal["checking", "savings"] -> Literal["checking", "saving"]

Contract: accountType = ['checking', 'saving'] (singular). The API's own payout code branches on the literal string 'saving'. The plural "savings" is a value the API has never accepted -- not an alternate spelling choice, a value that fails.

4. CreateCustodialWalletInput: add name: str (required) and external_id: NotRequired[Optional[str]]

CreateWalletIn.required on the wire is ['network', 'name']; external_id is present and optional (["string","null"]). Before this PR, CreateCustodialWalletInput modeled only customer_id and network -- every custodial wallet creation through this SDK was rejected by the API for a missing required field. name is a bare required key here (not NotRequired) because the API genuinely requires it; unlike a normal "new optional field on an already-published TypedDict" case, there is no previously-working caller to protect, since every prior call was already failing server-side. node/go/swift already send name; python and php did not.

No method code change was needed: create() already forwards every non-customer_id key verbatim (payload = {k: v for k, v in data.items() if k != "customer_id"}), so name/external_id now flow through automatically once the type carries them -- proven by the updated mock_request.assert_called_once_with(...) body assertions in test_custodial_wallets.py.

unmodeled.json cleanup

Removed the four now-fixed entries (stale records misdirect the next reader):

• {"kind": "enum", "enum": "BankAccountType", "missing_values": ["saving"]}
• {"kind": "property", "schema": "CreateWalletIn", "field": "name"}
• {"kind": "property", "schema": "CreateWalletIn", "field": "external_id"}
• {"kind": "property", "schema": "CreatePayinOut", "field": "billing_fee_amount"}

KycStatus's divergence (2 of 8 members modeled) is untouched -- separate, still undecided, not part of this PR.

142 -> 138 entries.

--audit-types delta

BEFORE (316 findings):
  PayinOut.billing_fee_amount (Payin in .../payins/payins.py): spec type `number` (expected `float`) but SDK annotation is `str` [annotation: Optional[str]]
  PaginationMetadata.next_page (PaginationMetadata in .../types.py): spec is nullable but SDK annotation `int` has no Optional[...] [annotation: int]
  PaginationMetadata.prev_page (PaginationMetadata in .../types.py): spec is nullable but SDK annotation `int` has no Optional[...] [annotation: int]

AFTER (313 findings):
  (zero matches for billing_fee_amount / next_page / prev_page)

Drop of exactly 3 -- exactly the type-mismatch findings this PR fixes. BankAccountType and the wallet-create fields are presence/enum-divergence issues tracked in unmodeled.json, not --audit-types findings (that tool only flags type mismatches on properties the SDK already models); those are the 4 entries removed from unmodeled.json above.

sync.py --check stays exit 0 (silent) before and after -- these are hand-authored type corrections, not spec-drift the patcher would have applied differently.

Tests

• New tests/test_types.py: explicit TypedDict-annotated literals for all four fixes, so pyright/mypy (both run over tests/) enforce the shape at the assignment, not just a runtime equality check -- a string next_page, a numeric billing_fee_amount (plus proof the field is optional on GetPayinTrackResponse/CreateEvmPayinResponse), "saving" as a valid BankAccountType, and name/external_id on CreateCustodialWalletInput.
• Updated test_payouts.py/test_payins.py: pagination fixtures now use string cursors ("pi_123") instead of integers.
• Updated test_custodial_wallets.py: both test_create_custodial_wallet (async + sync) now pass name and assert it's in the actual POST body sent; new test_create_custodial_wallet_with_external_id proves external_id flows through when supplied.

Proof

$ uv sync --group dev --group test
Resolved 28 packages ... Checked 27 packages

$ uv run ruff format --check .
72 files already formatted

$ uv run ruff check .
All checks passed!

$ uv run pyright
0 errors, 0 warnings, 0 informations

$ uv run mypy .
Success: no issues found in 69 source files

$ uv run pytest --tb=short -q
...
215 passed in 1.00s

$ python3 .api-sync/check_contract.py
Checked 1347 declared TypedDict fields across 175 classes against 527 known wire keys.
Direction B (fields) -- warning only: 232 spec property name(s) are not declared by any SDK TypedDict.
Direction A and B: PASSED.

$ python3 .api-sync/sync.py --validate-map
Map validity: OK

$ python3 .api-sync/sync.py --check
(silent, exit 0)

Determinism (two independent copies of this branch, sync.py --apply --spec .api-sync/spec-snapshot.json re-run in each -- unaffected by these hand-authored fixes, confirming the patcher itself is untouched and still behaves correctly):

No changes.
No changes.
$ diff -rq /tmp/fix-det-a /tmp/fix-det-b
(no output -- byte-identical)

Version bump

Title uses feat: to produce a minor bump (these change public TypedDict/Literal shapes, not just internal behavior). Not fix: (patch) because the task explicitly calls for minor given the type-surface change, and not feat!:/breaking (these correct wrong types to match an unchanged wire contract; nothing that previously worked correctly stops working).

Per the working rules: fresh clone, branch off current main (post #58/#59/#60/#61/#62), not merged, opening for review and stopping here.

https://claude.ai/code/session_01F1stiNzuNtJXoXtiW9ZCbs

[BernardoSM]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.