Add customer.* webhook events and customer_id list filters (wave 1)

.changeset/customer-webhooks-and-list-filters.md

@@ -0,0 +1,7 @@
+---
+"@blindpay/node": minor
+---
+
+Add `customer.new`, `customer.update` and `customer.delete` to `WebhookEvents` (the deployed API has been dual-emitting these alongside the legacy `receiver.*` events since June). Mark the `receiver.*` webhook events `@deprecated` in place; they still fire and are not removed.
+
+Add `customer_id` as an accepted filter on `ListPayinsInput` and `ListPayoutsInput`, matching what the deployed API already accepts. Drop the internal `customer_id`/`customer_name` -> `receiver_id`/`receiver_name` query translation in the `customers` resource's `list()` now that the deployed API accepts the `customer_*` filter names natively.

CLAUDE.md

@@ -71,8 +71,8 @@ All types are defined in the same file as the factory function, above it. Naming
 | Create response | `CreatePartnerFeeResponse` |
 | Get input | `GetPayinInput` |
 | Get response | `GetPayinResponse` |
-| Update input | `UpdateReceiverInput` |
-| Delete input | `DeleteReceiverInput` |
+| Update input | `UpdateCustomerInput` |
+| Delete input | `DeleteCustomerInput` |
 | String-only IDs | `export type GetPayinInput = string;` |
 | Object inputs | `export type CreatePayoutInput = { ... };` |
 
@@ -724,18 +724,18 @@ update({ widget_id, ...data }: UpdateWidgetInput): Promise<BlindpayApiResponse<v
 3. **Nested resource IDs**: all IDs come from the input object.
 ```typescript
 export type GetOfframpWalletInput = {
-    receiver_id: string;
+    customer_id: string;
     bank_account_id: string;
     id: string;
 };
 
 get({
-    receiver_id,
+    customer_id,
     bank_account_id,
     id,
 }: GetOfframpWalletInput): Promise<BlindpayApiResponse<GetOfframpWalletResponse>> {
     return client.get(
-        `/instances/${instanceId}/receivers/${receiver_id}/bank-accounts/${bank_account_id}/offramp-wallets/${id}`
+        `/instances/${instanceId}/customers/${customer_id}/bank-accounts/${bank_account_id}/offramp-wallets/${id}`
     );
 },
 ```
@@ -758,7 +758,7 @@ When one endpoint creates different variants based on a `type` field, create sep
 createIndividualWithStandardKYC(
     data: CreateIndividualWithStandardKYCInput
 ): Promise<BlindpayApiResponse<CreateIndividualWithStandardKYCResponse>> {
-    return client.post(`/instances/${instanceId}/receivers`, {
+    return client.post(`/instances/${instanceId}/customers`, {
         kyc_type: "standard",
         type: "individual",
         ...data,

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@blindpay/node",
-    "version": "4.0.2",
+    "version": "4.1.0",
     "description": "Official Node.js SDK for Blindpay API - Stablecoin API for global payments",
     "keywords": [
         "blindpay",

src/resources/customers/customers.test.ts

@@ -577,7 +577,7 @@ describe("Customers", () => {
             const mockedLimitIncreaseRequests: GetLimitIncreaseRequestsResponse = [
                 {
                     id: "rl_000000000000",
-                    customer_id: "re_YuaMcI2B8zbQ",
+                    receiver_id: "re_YuaMcI2B8zbQ",
                     status: "in_review",
                     daily: 50000,
                     monthly: 250000,
@@ -589,7 +589,7 @@ describe("Customers", () => {
                 },
                 {
                     id: "rl_000000000000",
-                    customer_id: "re_YuaMcI2B8zbQ",
+                    receiver_id: "re_YuaMcI2B8zbQ",
                     status: "approved",
                     daily: 30000,
                     monthly: 150000,
@@ -618,7 +618,7 @@ describe("Customers", () => {
             const mockedLimitIncreaseRequests: GetLimitIncreaseRequestsResponse = [
                 {
                     id: "rl_000000000000",
-                    customer_id: "re_YuaMcI2B8zbQ",
+                    receiver_id: "re_YuaMcI2B8zbQ",
                     status: "approved",
                     daily: 50000,
                     monthly: 250000,

src/resources/customers/index.ts

@@ -73,7 +73,7 @@ export type Owner = {
     title: string | null;
     tax_type?: OwnerTaxType | null;
     instance_id?: string;
-    customer_id?: string;
+    receiver_id?: string;
 };
 
 export type IndividualWithStandardKYC = {
@@ -485,7 +485,7 @@ export type LimitIncreaseRequestSupportingDocumentType =
 
 export type GetLimitIncreaseRequestsResponse = Array<{
     id: string;
-    customer_id: string;
+    receiver_id: string;
     status: LimitIncreaseRequestStatus;
     daily: number;
     monthly: number;
@@ -515,19 +515,7 @@ export type RequestLimitIncreaseResponse = {
 export function createCustomersResource(instanceId: string, client: InternalApiClient) {
     return {
         list(params?: ListCustomersInput): Promise<BlindpayApiResponse<ListCustomersResponse>> {
-            // The API's filter schema still uses receiver_id/receiver_name. Translate
-            // customer_* inputs to the wire-level names so consumers see a clean
-            // customer-only surface. Drop this mapping once the API accepts customer_*.
-            const wireParams = params
-                ? Object.fromEntries(
-                      Object.entries(params).map(([k, v]) => {
-                          if (k === "customer_id") return ["receiver_id", v];
-                          if (k === "customer_name") return ["receiver_name", v];
-                          return [k, v];
-                      })
-                  )
-                : undefined;
-            const queryParams = wireParams ? `?${new URLSearchParams(wireParams)}` : "";
+            const queryParams = params ? `?${new URLSearchParams(params)}` : "";
             return client.get(`/instances/${instanceId}/customers${queryParams}`);
         },
         createIndividualWithStandardKYC(

src/resources/payins/index.ts

@@ -99,6 +99,7 @@ export type Payin = {
 export type ListPayinsInput = PaginationParams & {
     status?: TransactionStatus;
     receiver_id?: string;
+    customer_id?: string;
 };
 
 export type ListPayinsResponse =

src/resources/payouts/index.ts

@@ -96,6 +96,7 @@ export type Payout = {
 
 export type ListPayoutsInput = PaginationParams & {
     receiver_id?: string;
+    customer_id?: string;
 };
 
 export type ListPayoutsResponse = {

src/resources/wallets/blockchain.test.ts

@@ -40,7 +40,7 @@ describe("Blockchain wallets", () => {
                     address: "0xDD6a3aD0949396e57C7738ba8FC1A46A5a1C372C",
                     signature_tx_hash: "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
                     is_account_abstraction: false,
-                    customer_id: "re_000000000000",
+                    receiver_id: "re_000000000000",
                 },
             ];
 
@@ -64,7 +64,7 @@ describe("Blockchain wallets", () => {
                 address: "0xDD6a3aD0949396e57C7738ba8FC1A46A5a1C372C",
                 signature_tx_hash: undefined,
                 is_account_abstraction: true,
-                customer_id: "re_000000000000",
+                receiver_id: "re_000000000000",
             };
 
             fetchMock.mockResponseOnce(JSON.stringify(mockedWallet), {
@@ -92,7 +92,7 @@ describe("Blockchain wallets", () => {
                 address: "0xDD6a3aD0949396e57C7738ba8FC1A46A5a1C372C",
                 signature_tx_hash: "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
                 is_account_abstraction: false,
-                customer_id: "re_000000000000",
+                receiver_id: "re_000000000000",
             };
 
             fetchMock.mockResponseOnce(JSON.stringify(mockedWallet), {
@@ -120,7 +120,7 @@ describe("Blockchain wallets", () => {
                 address: "0xDD6a3aD0949396e57C7738ba8FC1A46A5a1C372C",
                 signature_tx_hash: "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
                 is_account_abstraction: false,
-                customer_id: "re_000000000000",
+                receiver_id: "re_000000000000",
             };
 
             fetchMock.mockResponseOnce(JSON.stringify(mockedWallet), {

src/resources/wallets/blockchain.ts

@@ -16,7 +16,7 @@ export type ListBlockchainWalletsResponse = Array<{
     address?: string;
     signature_tx_hash?: string;
     is_account_abstraction: boolean;
-    customer_id: string;
+    receiver_id: string;
 }>;
 
 export type CreateBlockchainWalletWithAddressInput = {
@@ -50,7 +50,7 @@ export type GetBlockchainWalletResponse = {
     address?: string;
     signature_tx_hash?: string;
     is_account_abstraction: boolean;
-    customer_id: string;
+    receiver_id: string;
 };
 
 export type CreateBlockchainWalletResponse = {
@@ -60,7 +60,7 @@ export type CreateBlockchainWalletResponse = {
     address?: string;
     signature_tx_hash?: string;
     is_account_abstraction: boolean;
-    customer_id: string;
+    receiver_id: string;
 };
 
 export type CreateAssetTrustlineInput = string;

src/resources/wallets/offramp.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it } from "vitest";
 import { BlindPay } from "../../client";
+import type { OfframpWallet } from "./offramp";
 
 describe("Offramp wallets", () => {
     afterEach(() => fetchMock.resetMocks());
@@ -8,12 +9,12 @@ describe("Offramp wallets", () => {
 
     describe("List offramp wallets", () => {
         it("should list offramp wallets", async () => {
-            const mockedOfframpWallets = [
+            const mockedOfframpWallets: OfframpWallet[] = [
                 {
                     id: "ow_000000000000",
                     external_id: "your_external_id",
                     instance_id: "in_000000000000",
-                    customer_id: "re_000000000000",
+                    receiver_id: "re_000000000000",
                     bank_account_id: "ba_000000000000",
                     network: "tron",
                     address: "TALJN9zTTEL9TVBb4WuTt6wLvPqJZr3hvb",
@@ -87,11 +88,11 @@ describe("Offramp wallets", () => {
 
     describe("Get offramp wallet", () => {
         it("should get an offramp wallet", async () => {
-            const mockedOfframpWallet = {
+            const mockedOfframpWallet: OfframpWallet = {
                 id: "ow_000000000000",
                 external_id: "your_external_id",
                 instance_id: "in_000000000000",
-                customer_id: "re_000000000000",
+                receiver_id: "re_000000000000",
                 bank_account_id: "ba_000000000000",
                 network: "tron",
                 address: "TALJN9zTTEL9TVBb4WuTt6wLvPqJZr3hvb",

src/resources/wallets/offramp.ts

@@ -18,7 +18,7 @@ export type OfframpWallet = {
     id: string;
     external_id: string;
     instance_id: string;
-    customer_id: string;
+    receiver_id: string;
     bank_account_id: string;
     network: OfframpWalletNetwork;
     address: string;

src/resources/webhooks/index.ts

@@ -2,8 +2,8 @@ import type { BlindpayApiResponse } from "../../../types";
 import type { InternalApiClient } from "../../internal/api-client";
 
 export type WebhookEvents =
-    | "receiver.new"
-    | "receiver.update"
+    | "receiver.new" // @deprecated use "customer.new" instead
+    | "receiver.update" // @deprecated use "customer.update" instead
     | "bankAccount.new"
     | "payout.new"
     | "payout.update"
@@ -24,7 +24,10 @@ export type WebhookEvents =
     | "transfer.complete"
     | "wallet.new"
     | "wallet.inbound"
-    | "receiver.delete";
+    | "receiver.delete" // @deprecated use "customer.delete" instead
+    | "customer.new"
+    | "customer.update"
+    | "customer.delete";
 
 export type CreateWebhookEndpointInput = {
     url: string;