feat(customers): add customer.* webhook events and customer_id list filters (#52)

* feat(customers): add customer.* webhook events and customer_id list filters

The deployed API already accepts these; this is additive and safe against
production today.

- Add customer.new/customer.update/customer.delete to the WebhookEvents
  Literal, and fold the previously orphaned receiver.delete (from
  src/blindpay/types.py, disconnected from WebhookEvents and never wired
  up) into the same Literal alongside it.
- Mark receiver.new/receiver.update/receiver.delete deprecated with a
  comment pointing at the same changelog post used by the receivers
  namespace deprecation warning in client.py. They are not removed:
  receiver.* webhooks are still dual-emitted by the deployed API.
- Retire the stray, publicly exported types.WebhookEvent alias now that
  receiver.delete lives in WebhookEvents.
- Add customer_id as an optional list filter on ListPayinsInput and
  ListPayoutsInput, alongside the existing receiver_id (not removed).
  GET /v1/instances/{id}/payins and /payouts already accept customer_id
  as a query filter in the deployed API spec.
- Update the README quickstart example to use blindpay.customers.get()
  instead of the runtime-deprecated blindpay.receivers.get().

Deliberately excluded (wave 2, needs blindpay-v2 PR #1799 deployed
first): the remaining 11 receiver_* -> customer_* field renames, and
removal of receiver.* from the webhook enum. Shipping those today would
break every SDK user still on the deployed field names.

Claude-Session: https://claude.ai/code/session_01F1stiNzuNtJXoXtiW9ZCbs

* fix: keep the WebhookEvent export so this release stays additive

The branch had deleted the public `WebhookEvent` alias from types.py and dropped it
from __init__.py's imports and __all__. It is dead inside the repo, but it is an
exported symbol, so `from blindpay import WebhookEvent` would break on what is
otherwise a purely additive minor release.

Restored with its original value and a deprecation note pointing at WebhookEvents,
which is the alias that actually lists every event. Removal belongs in the next major,
alongside dropping the receiver.* members.

Claude-Session: https://claude.ai/code/session_01F1stiNzuNtJXoXtiW9ZCbs

* fix(customers): align response field names with the deployed API

The customer.* rename shims declared customer_id on nested owners,
limit-increase requests, blockchain wallets, and offramp wallets.
The deployed API still sends receiver_id in all four places (server-side
customers rename is not deployed yet). Since these are TypedDicts, a
consumer indexing the declared key gets a KeyError today.

Verified against apps/api/openapi.json: ReceiverOut.owners[], required
receiver_id on BlockchainWalletOut, OfframpWallet, and
GetReceiverLimitIncreaseOut. Updated the wallet test fixtures to match
and added receiver_id assertions so a regression of this exact bug fails
the suite.

bank_accounts.py's owners field is untouched: the deployed
BankAccountOut has neither receiver_id nor customer_id, so that is a
separate pre-existing type-accuracy issue, not this bug.

Claude-Session: https://claude.ai/code/session_01F1stiNzuNtJXoXtiW9ZCbs

* fix(tests): narrow Optional data before subscripting in wallet list assertions

pyright flagged reportOptionalSubscript on response["data"][0] since
BlindpayApiResponse["data"] is Optional. Add the same is-not-None assert
already used elsewhere in the suite to narrow the type.

Claude-Session: https://claude.ai/code/session_01F1stiNzuNtJXoXtiW9ZCbs

* fix(customers): declare customer_id where the middleware alias sends it

Blockchain wallets, offramp wallets and limit-increase responses go through
addCustomerIdMiddleware, which adds customer_id wherever receiver_id is
present today, and both are required in the post-#1799 spec. Revert the
earlier reversion to receiver_id for those three.

Owner is different: it's a nested owners[] element, which the middleware
does not recurse into, so customer_id is not sent today but will be after
#1799. Declare both keys as NotRequired so neither shape breaks.

Claude-Session: https://claude.ai/code/session_01F1stiNzuNtJXoXtiW9ZCbs

Author: ericviana

README.md

@@ -27,14 +27,14 @@ All API methods return a response dictionary with either `data` or `error`:
         instance_id="your_instance_id_here"
     )
 
-    response = await blindpay.receivers.get("receiver-id")
+    response = await blindpay.customers.get("customer-id")
 
     if response['error']:
         print(f"Error: {response['error']['message']}")
         return
 
-    receiver = response['data']
-    print(f"Receiver: {receiver}")
+    customer = response['data']
+    print(f"Customer: {customer}")
 ```
 
 ## Types

src/blindpay/resources/customers/customers.py

@@ -1,7 +1,7 @@
 from typing import List, Optional, Union
 from urllib.parse import urlencode
 
-from typing_extensions import Literal, TypedDict
+from typing_extensions import Literal, NotRequired, TypedDict
 
 from ..._internal.api_client import InternalApiClient, InternalApiClientSync
 from ...types import (
@@ -302,7 +302,10 @@ class TransactionLimit(TypedDict):
 class Owner(TypedDict):
     id: str
     instance_id: str
-    customer_id: str
+    # Not yet added by the response middleware for nested owners; both keys are
+    # optional until the API sends customer_id here directly (post-#1799).
+    receiver_id: NotRequired[str]
+    customer_id: NotRequired[str]
     role: OwnerRole
     first_name: str
     last_name: str

src/blindpay/resources/payins/payins.py

@@ -103,6 +103,7 @@ class Payin(TypedDict):
 class ListPayinsInput(PaginationParams):
     status: Optional[TransactionStatus]
     receiver_id: Optional[str]
+    customer_id: Optional[str]
 
 
 class ListPayinsResponse(TypedDict):

src/blindpay/resources/payouts/payouts.py

@@ -103,6 +103,7 @@ class Payout(TypedDict):
 
 class ListPayoutsInput(PaginationParams, total=False):
     receiver_id: str
+    customer_id: str
 
 
 class ListPayoutsResponse(TypedDict):

src/blindpay/resources/webhooks/webhooks.py

@@ -6,8 +6,18 @@
 from ...types import BlindpayApiResponse
 
 WebhookEvents = Literal[
+    # deprecated: use "customer.new" instead. See
+    # https://www.blindpay.com/changelog/2026-06-04-customers-rename
     "receiver.new",
+    # deprecated: use "customer.update" instead. See
+    # https://www.blindpay.com/changelog/2026-06-04-customers-rename
     "receiver.update",
+    # deprecated: use "customer.delete" instead. See
+    # https://www.blindpay.com/changelog/2026-06-04-customers-rename
+    "receiver.delete",
+    "customer.new",
+    "customer.update",
+    "customer.delete",
     "bankAccount.new",
     "payout.new",
     "payout.update",

src/blindpay/types.py

@@ -408,5 +408,7 @@ class TrackingPartnerFee(TypedDict):
 
 ManualExecutionStatus = Literal["failed"]
 
-
+# Deprecated: use WebhookEvents from blindpay.resources.webhooks, which lists every
+# event. Kept exported so this stays an additive release; scheduled for removal in the
+# next major.
 WebhookEvent = Literal["receiver.delete"]

tests/resources/test_blockchain_wallets.py

@@ -46,6 +46,8 @@ async def test_list_blockchain_wallets(self):
 
             assert response["error"] is None
             assert response["data"] == mocked_wallets
+            assert response["data"] is not None
+            assert response["data"][0]["customer_id"] == "re_000000000000"
             mock_request.assert_called_once_with(
                 "GET", "/instances/in_000000000000/customers/re_000000000000/blockchain-wallets"
             )
@@ -326,6 +328,8 @@ def test_list_blockchain_wallets(self):
 
             assert response["error"] is None
             assert response["data"] == mocked_wallets
+            assert response["data"] is not None
+            assert response["data"][0]["customer_id"] == "re_000000000000"
             mock_request.assert_called_once_with(
                 "GET", "/instances/in_000000000000/customers/re_000000000000/blockchain-wallets"
             )

tests/resources/test_offramp_wallets.py

@@ -38,6 +38,8 @@ async def test_list_offramp_wallets(self):
 
             assert response["error"] is None
             assert response["data"] == mocked_offramp_wallets
+            assert response["data"] is not None
+            assert response["data"][0]["customer_id"] == "re_000000000000"
             mock_request.assert_called_once_with(
                 "GET",
                 "/instances/in_000000000000/customers/re_000000000000/bank-accounts/ba_000000000000/offramp-wallets",