feat: add support for attaching payments to existing customers

.stats.yml

@@ -1 +1 @@
-configured_endpoints: 41
+configured_endpoints: 45

api.md

@@ -164,6 +164,21 @@ Methods:
 
 - <code title="get /v3/available_number">client.available_number.<a href="./src/linq/resources/available_number.py">retrieve</a>(\*\*<a href="src/linq/types/available_number_retrieve_params.py">params</a>) -> <a href="./src/linq/types/available_number_retrieve_response.py">AvailableNumberRetrieveResponse</a></code>
 
+# PaymentRequests
+
+Types:
+
+```python
+from linq.types import PaymentRequest, PaymentRequestListResponse
+```
+
+Methods:
+
+- <code title="post /v3/payment_requests">client.payment_requests.<a href="./src/linq/resources/payment_requests.py">create</a>(\*\*<a href="src/linq/types/payment_request_create_params.py">params</a>) -> <a href="./src/linq/types/payment_request.py">PaymentRequest</a></code>
+- <code title="get /v3/payment_requests/{paymentRequestId}">client.payment_requests.<a href="./src/linq/resources/payment_requests.py">retrieve</a>(payment_request_id) -> <a href="./src/linq/types/payment_request.py">PaymentRequest</a></code>
+- <code title="get /v3/payment_requests">client.payment_requests.<a href="./src/linq/resources/payment_requests.py">list</a>(\*\*<a href="src/linq/types/payment_request_list_params.py">params</a>) -> <a href="./src/linq/types/payment_request_list_response.py">PaymentRequestListResponse</a></code>
+- <code title="post /v3/payment_requests/{paymentRequestId}/cancel">client.payment_requests.<a href="./src/linq/resources/payment_requests.py">cancel</a>(payment_request_id) -> <a href="./src/linq/types/payment_request.py">PaymentRequest</a></code>
+
 # WebhookEvents
 
 Types:

scripts/lint

@@ -13,7 +13,7 @@ else
 fi
 
 echo "==> Running pyright"
-uv run pyright
+uv run pyright -p .
 
 echo "==> Running mypy"
 uv run mypy .

src/linq/resources/__init__.py

@@ -73,6 +73,14 @@
     AvailableNumberResourceWithStreamingResponse,
     AsyncAvailableNumberResourceWithStreamingResponse,
 )
+from .payment_requests import (
+    PaymentRequestsResource,
+    AsyncPaymentRequestsResource,
+    PaymentRequestsResourceWithRawResponse,
+    AsyncPaymentRequestsResourceWithRawResponse,
+    PaymentRequestsResourceWithStreamingResponse,
+    AsyncPaymentRequestsResourceWithStreamingResponse,
+)
 from .webhook_subscriptions import (
     WebhookSubscriptionsResource,
     AsyncWebhookSubscriptionsResource,
@@ -119,6 +127,12 @@
     "AsyncAvailableNumberResourceWithRawResponse",
     "AvailableNumberResourceWithStreamingResponse",
     "AsyncAvailableNumberResourceWithStreamingResponse",
+    "PaymentRequestsResource",
+    "AsyncPaymentRequestsResource",
+    "PaymentRequestsResourceWithRawResponse",
+    "AsyncPaymentRequestsResourceWithRawResponse",
+    "PaymentRequestsResourceWithStreamingResponse",
+    "AsyncPaymentRequestsResourceWithStreamingResponse",
     "WebhookEventsResource",
     "AsyncWebhookEventsResource",
     "WebhookEventsResourceWithRawResponse",

src/linq/resources/available_number.py

@@ -67,9 +67,11 @@ def retrieve(
         reusing the line an existing chat with those recipients is already on. Without
         `to`, the best healthy line is chosen.
 
-        This is advisory: it does not reserve the line or change selection state. Pass
-        the returned `phone_number` as `from` when you create the chat to guarantee the
-        same line.
+        This does not reserve the line. Without `to`, the least-recently-used healthy
+        line is returned — suggestions and your own sends (including an explicit `from`
+        on chat creation) both count as use, so successive calls cycle through your
+        healthy lines and traffic spreads evenly. Pass the returned `phone_number` as
+        `from` when you create the chat to guarantee the same line.
 
         Also returns `vcf_url`: a time-limited link to a vCard (`.vcf`) for the chosen
         line, carrying its contact card (name/photo) with the chosen number as the
@@ -148,9 +150,11 @@ async def retrieve(
         reusing the line an existing chat with those recipients is already on. Without
         `to`, the best healthy line is chosen.
 
-        This is advisory: it does not reserve the line or change selection state. Pass
-        the returned `phone_number` as `from` when you create the chat to guarantee the
-        same line.
+        This does not reserve the line. Without `to`, the least-recently-used healthy
+        line is returned — suggestions and your own sends (including an explicit `from`
+        on chat creation) both count as use, so successive calls cycle through your
+        healthy lines and traffic spreads evenly. Pass the returned `phone_number` as
+        `from` when you create the chat to guarantee the same line.
 
         Also returns `vcf_url`: a time-limited link to a vCard (`.vcf`) for the chosen
         line, carrying its contact card (name/photo) with the chosen number as the

src/linq/resources/chats/chats.py

@@ -172,14 +172,43 @@ def messages(self) -> MessagesResource:
 
     @cached_property
     def location(self) -> LocationResource:
-        """Request and retrieve real-time location data via iMessage.
-
-        Use these endpoints to request a contact's location, retrieve location data
-        for contacts who are sharing with you, and subscribe to webhooks when someone
-        starts or stops sharing their location.
+        """
+        Request a contact's location, retrieve location for contacts sharing with you,
+        and subscribe to webhooks when someone starts or stops sharing.
 
         **Coordinates** are returned in [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) format:
         `[longitude, latitude]` or `[longitude, latitude, altitude]` if altitude is available.
+
+        ### Reading location is poll-based
+
+        Poll `GET /v3/chats/{chatId}/location` whenever you need the latest position.
+        **There is no webhook that pushes updated coordinates** — the
+        `location.sharing.started` / `location.sharing.stopped` webhooks fire only when a
+        contact begins or ends sharing, not on each position update. To track a moving
+        contact, poll the `GET` endpoint.
+
+        ### Freshness
+
+        Each feature's `properties.updated_at` tells you when that participant's
+        location was last updated — use it to judge freshness.
+
+        ### Polling guidance
+
+        Locations refresh on Apple's cadence, not per request — polling faster than a
+        participant's location actually updates just returns the same position. Poll at a
+        modest interval (for example, once every few minutes per chat) rather than
+        continuously.
+
+        ### Why is location empty after `location.sharing.started` fired?
+
+        If the contact started sharing from the **standalone Find My app** instead of the
+        Messages conversation, the share may be tied to their **Apple ID email** rather
+        than their phone number — the webhook's `shared_by` field shows the email in that
+        case. Location is readable only through a chat with the handle that shared, so
+        `GET /v3/chats/{chatId}/location` on the phone-number chat stays empty.
+
+        The fix: have the contact stop sharing and re-share from **Find My inside the
+        Messages conversation** with your number.
         """
         return LocationResource(self._client)
 
@@ -764,14 +793,43 @@ def messages(self) -> AsyncMessagesResource:
 
     @cached_property
     def location(self) -> AsyncLocationResource:
-        """Request and retrieve real-time location data via iMessage.
-
-        Use these endpoints to request a contact's location, retrieve location data
-        for contacts who are sharing with you, and subscribe to webhooks when someone
-        starts or stops sharing their location.
+        """
+        Request a contact's location, retrieve location for contacts sharing with you,
+        and subscribe to webhooks when someone starts or stops sharing.
 
         **Coordinates** are returned in [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) format:
         `[longitude, latitude]` or `[longitude, latitude, altitude]` if altitude is available.
+
+        ### Reading location is poll-based
+
+        Poll `GET /v3/chats/{chatId}/location` whenever you need the latest position.
+        **There is no webhook that pushes updated coordinates** — the
+        `location.sharing.started` / `location.sharing.stopped` webhooks fire only when a
+        contact begins or ends sharing, not on each position update. To track a moving
+        contact, poll the `GET` endpoint.
+
+        ### Freshness
+
+        Each feature's `properties.updated_at` tells you when that participant's
+        location was last updated — use it to judge freshness.
+
+        ### Polling guidance
+
+        Locations refresh on Apple's cadence, not per request — polling faster than a
+        participant's location actually updates just returns the same position. Poll at a
+        modest interval (for example, once every few minutes per chat) rather than
+        continuously.
+
+        ### Why is location empty after `location.sharing.started` fired?
+
+        If the contact started sharing from the **standalone Find My app** instead of the
+        Messages conversation, the share may be tied to their **Apple ID email** rather
+        than their phone number — the webhook's `shared_by` field shows the email in that
+        case. Location is readable only through a chat with the handle that shared, so
+        `GET /v3/chats/{chatId}/location` on the phone-number chat stays empty.
+
+        The fix: have the contact stop sharing and re-share from **Find My inside the
+        Messages conversation** with your number.
         """
         return AsyncLocationResource(self._client)
 
@@ -1384,14 +1442,43 @@ def messages(self) -> MessagesResourceWithRawResponse:
 
     @cached_property
     def location(self) -> LocationResourceWithRawResponse:
-        """Request and retrieve real-time location data via iMessage.
-
-        Use these endpoints to request a contact's location, retrieve location data
-        for contacts who are sharing with you, and subscribe to webhooks when someone
-        starts or stops sharing their location.
+        """
+        Request a contact's location, retrieve location for contacts sharing with you,
+        and subscribe to webhooks when someone starts or stops sharing.
 
         **Coordinates** are returned in [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) format:
         `[longitude, latitude]` or `[longitude, latitude, altitude]` if altitude is available.
+
+        ### Reading location is poll-based
+
+        Poll `GET /v3/chats/{chatId}/location` whenever you need the latest position.
+        **There is no webhook that pushes updated coordinates** — the
+        `location.sharing.started` / `location.sharing.stopped` webhooks fire only when a
+        contact begins or ends sharing, not on each position update. To track a moving
+        contact, poll the `GET` endpoint.
+
+        ### Freshness
+
+        Each feature's `properties.updated_at` tells you when that participant's
+        location was last updated — use it to judge freshness.
+
+        ### Polling guidance
+
+        Locations refresh on Apple's cadence, not per request — polling faster than a
+        participant's location actually updates just returns the same position. Poll at a
+        modest interval (for example, once every few minutes per chat) rather than
+        continuously.
+
+        ### Why is location empty after `location.sharing.started` fired?
+
+        If the contact started sharing from the **standalone Find My app** instead of the
+        Messages conversation, the share may be tied to their **Apple ID email** rather
+        than their phone number — the webhook's `shared_by` field shows the email in that
+        case. Location is readable only through a chat with the handle that shared, so
+        `GET /v3/chats/{chatId}/location` on the phone-number chat stays empty.
+
+        The fix: have the contact stop sharing and re-share from **Find My inside the
+        Messages conversation** with your number.
         """
         return LocationResourceWithRawResponse(self._chats.location)
 
@@ -1532,14 +1619,43 @@ def messages(self) -> AsyncMessagesResourceWithRawResponse:
 
     @cached_property
     def location(self) -> AsyncLocationResourceWithRawResponse:
-        """Request and retrieve real-time location data via iMessage.
-
-        Use these endpoints to request a contact's location, retrieve location data
-        for contacts who are sharing with you, and subscribe to webhooks when someone
-        starts or stops sharing their location.
+        """
+        Request a contact's location, retrieve location for contacts sharing with you,
+        and subscribe to webhooks when someone starts or stops sharing.
 
         **Coordinates** are returned in [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) format:
         `[longitude, latitude]` or `[longitude, latitude, altitude]` if altitude is available.
+
+        ### Reading location is poll-based
+
+        Poll `GET /v3/chats/{chatId}/location` whenever you need the latest position.
+        **There is no webhook that pushes updated coordinates** — the
+        `location.sharing.started` / `location.sharing.stopped` webhooks fire only when a
+        contact begins or ends sharing, not on each position update. To track a moving
+        contact, poll the `GET` endpoint.
+
+        ### Freshness
+
+        Each feature's `properties.updated_at` tells you when that participant's
+        location was last updated — use it to judge freshness.
+
+        ### Polling guidance
+
+        Locations refresh on Apple's cadence, not per request — polling faster than a
+        participant's location actually updates just returns the same position. Poll at a
+        modest interval (for example, once every few minutes per chat) rather than
+        continuously.
+
+        ### Why is location empty after `location.sharing.started` fired?
+
+        If the contact started sharing from the **standalone Find My app** instead of the
+        Messages conversation, the share may be tied to their **Apple ID email** rather
+        than their phone number — the webhook's `shared_by` field shows the email in that
+        case. Location is readable only through a chat with the handle that shared, so
+        `GET /v3/chats/{chatId}/location` on the phone-number chat stays empty.
+
+        The fix: have the contact stop sharing and re-share from **Find My inside the
+        Messages conversation** with your number.
         """
         return AsyncLocationResourceWithRawResponse(self._chats.location)
 
@@ -1680,14 +1796,43 @@ def messages(self) -> MessagesResourceWithStreamingResponse:
 
     @cached_property
     def location(self) -> LocationResourceWithStreamingResponse:
-        """Request and retrieve real-time location data via iMessage.
-
-        Use these endpoints to request a contact's location, retrieve location data
-        for contacts who are sharing with you, and subscribe to webhooks when someone
-        starts or stops sharing their location.
+        """
+        Request a contact's location, retrieve location for contacts sharing with you,
+        and subscribe to webhooks when someone starts or stops sharing.
 
         **Coordinates** are returned in [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) format:
         `[longitude, latitude]` or `[longitude, latitude, altitude]` if altitude is available.
+
+        ### Reading location is poll-based
+
+        Poll `GET /v3/chats/{chatId}/location` whenever you need the latest position.
+        **There is no webhook that pushes updated coordinates** — the
+        `location.sharing.started` / `location.sharing.stopped` webhooks fire only when a
+        contact begins or ends sharing, not on each position update. To track a moving
+        contact, poll the `GET` endpoint.
+
+        ### Freshness
+
+        Each feature's `properties.updated_at` tells you when that participant's
+        location was last updated — use it to judge freshness.
+
+        ### Polling guidance
+
+        Locations refresh on Apple's cadence, not per request — polling faster than a
+        participant's location actually updates just returns the same position. Poll at a
+        modest interval (for example, once every few minutes per chat) rather than
+        continuously.
+
+        ### Why is location empty after `location.sharing.started` fired?
+
+        If the contact started sharing from the **standalone Find My app** instead of the
+        Messages conversation, the share may be tied to their **Apple ID email** rather
+        than their phone number — the webhook's `shared_by` field shows the email in that
+        case. Location is readable only through a chat with the handle that shared, so
+        `GET /v3/chats/{chatId}/location` on the phone-number chat stays empty.
+
+        The fix: have the contact stop sharing and re-share from **Find My inside the
+        Messages conversation** with your number.
         """
         return LocationResourceWithStreamingResponse(self._chats.location)
 
@@ -1828,13 +1973,42 @@ def messages(self) -> AsyncMessagesResourceWithStreamingResponse:
 
     @cached_property
     def location(self) -> AsyncLocationResourceWithStreamingResponse:
-        """Request and retrieve real-time location data via iMessage.
-
-        Use these endpoints to request a contact's location, retrieve location data
-        for contacts who are sharing with you, and subscribe to webhooks when someone
-        starts or stops sharing their location.
+        """
+        Request a contact's location, retrieve location for contacts sharing with you,
+        and subscribe to webhooks when someone starts or stops sharing.
 
         **Coordinates** are returned in [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) format:
         `[longitude, latitude]` or `[longitude, latitude, altitude]` if altitude is available.
+
+        ### Reading location is poll-based
+
+        Poll `GET /v3/chats/{chatId}/location` whenever you need the latest position.
+        **There is no webhook that pushes updated coordinates** — the
+        `location.sharing.started` / `location.sharing.stopped` webhooks fire only when a
+        contact begins or ends sharing, not on each position update. To track a moving
+        contact, poll the `GET` endpoint.
+
+        ### Freshness
+
+        Each feature's `properties.updated_at` tells you when that participant's
+        location was last updated — use it to judge freshness.
+
+        ### Polling guidance
+
+        Locations refresh on Apple's cadence, not per request — polling faster than a
+        participant's location actually updates just returns the same position. Poll at a
+        modest interval (for example, once every few minutes per chat) rather than
+        continuously.
+
+        ### Why is location empty after `location.sharing.started` fired?
+
+        If the contact started sharing from the **standalone Find My app** instead of the
+        Messages conversation, the share may be tied to their **Apple ID email** rather
+        than their phone number — the webhook's `shared_by` field shows the email in that
+        case. Location is readable only through a chat with the handle that shared, so
+        `GET /v3/chats/{chatId}/location` on the phone-number chat stays empty.
+
+        The fix: have the contact stop sharing and re-share from **Find My inside the
+        Messages conversation** with your number.
         """
         return AsyncLocationResourceWithStreamingResponse(self._chats.location)