fix: apply phone alias to recipients lists

[Arshgill01]

Summary

Rebased onto SDK 1.0 main. client.calls.create() now accepts recipient= / recipients= dicts in addition to phone=, and a dict written with the TypeScript-style phone key is aliased to phones before the number is resolved. Whatever the input shape, the request sent to POST /v2/calls uses the 1.0 single-target body with one phone field.

What changed

src/calle/calls.py

• create(): phone is now optional, and recipient: JsonObject | None and recipients: list[JsonObject] | None were added.
• Every recipient= / recipients= item goes through _normalize_recipient, which rewrites {"phone": x} to {"phones": [x]}. Items that already have phones are left as they are.
• New helper _target_from_recipients takes the single normalized item and returns (phone, region, locale): the first entry in phones, plus the item's region / locale unless the explicit region= / locale= kwargs are set, in which case the kwargs win.
• create() raises ValueError when:
  • recipient and recipients are both passed
  • phone is passed together with recipient or recipients
  • recipients holds anything other than exactly one item ("The Calls API does not support batch recipients.")
  • no phone number can be resolved

CHANGELOG.md: adds an [Unreleased] / Fixed entry.

1.0 wire format

In 1.0 the endpoint is /v2/calls and takes a single phone. This PR does not send a recipients array. For example, recipients=[{"phone": "+14155550100", "region": "US", "locale": "en-US"}] produces a body with "phone": "+14155550100", "region": "US", "locale": "en-US" and no recipients key. If you pass more than one recipient, the SDK raises before any request is made.

Tests

New tests in tests/test_calls.py, run offline against a respx mock (no live calls):

• test_create_call_aliases_phone_on_recipients_list
• test_create_call_aliases_phone_on_singular_recipient
• test_normalize_recipient_aliases_phone_to_phones

The first two check that the posted body has the resolved phone, region and locale, and has no recipients key.

Run on the rebased head efad48a:

uv run --locked pytest -q tests/test_calls.py
20 passed

uv run --locked pytest -q
68 passed

uv run --locked ruff check src/calle/calls.py tests/test_calls.py
All checks passed!

uv run --locked mypy src/calle
Success: no issues found in 6 source files

Source

From the CALL-E hackathon feedback lab: https://github.com/Arshgill01/ExactRef/blob/main/docs/feedback/lab/XR-110-python-recipients-skip-phone-alias.md

[Arshgill01]

@Ray-56 @Si40Code friendly nudge — quiet since Sep 14. Ready for review whenever you have a moment. No rush.