@vonpay/checkout-node 1.1.2 → 2.1.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { VonPayCheckoutConfig, CreateSessionParams, CheckoutSession, SessionStatus, DryRunResult, WebhookEvent, HealthStatus, RequestOptions, ReturnOutcome, ReturnParams, PaymentIntent, CreatePaymentIntentParams, CapturePaymentIntentParams, Capabilities, Refund, CreateRefundParams, Token, CreateTokenParams, WebhookSubscription, ListWebhookSubscriptionsParams, WebhookSubscriptionsList, WebhookEventRecord } from "./types.js";
+import type { VonPayCheckoutConfig, CreateSessionParams, CheckoutSession, SessionStatus, DryRunResult, WebhookEvent, HealthStatus, RequestOptions, ReturnOutcome, ReturnParams, PaymentIntent, CreatePaymentIntentParams, CapturePaymentIntentParams, Capabilities, Refund, CreateRefundParams, Token, CreateTokenParams, WebhookSubscription, ListWebhookSubscriptionsParams, WebhookSubscriptionsList, WebhookEventRecord, Buyer, UpsertBuyerParams, UpdateBuyerParams, FindBuyerParams } from "./types.js";
 export declare const KNOWN_RETURN_SCHEMES: readonly ["v1", "v2"];
 export type ReturnScheme = (typeof KNOWN_RETURN_SCHEMES)[number];
 export declare const DEFAULT_RETURN_SCHEMES: readonly ReturnScheme[];
@@ -165,6 +165,129 @@ export declare class VonPayCheckout {
      * the rest of `/v1/*` on this engine); the SDK exposes responses
      * pass-through with no key conversion.
      */
+    /**
+     * Stored shopper profiles. `vp_sk_*` Bearer required.
+     *
+     * The same profile the checkout flows write via `buyerId` / `buyerEmail`, so
+     * a buyer created here is the one a later payment attaches to.
+     *
+     * ⛔ **The erase is a separate method on purpose.** `PATCH /v1/buyers/:id`
+     * accepts `email: null` to permanently erase the address — irreversibly, and
+     * it removes the copy held at the payment provider too. The API's own docs
+     * warn that several common JSON libraries serialise absent optional fields as
+     * `null`, so an ordinary update can wipe a shopper's email with nobody
+     * intending it.
+     *
+     * This SDK refuses to expose that shape. `update()` cannot express `null` —
+     * it is a type error — and {@link eraseEmail} is the only path that sends it.
+     * An accidental erase is therefore not writable in TypeScript.
+     */
+    /**
+     * ⚠️ **No idempotency key on this resource, deliberately.**
+     *
+     * The canonical spec declares `Idempotency-Key` on `POST /v1/sessions` and
+     * `POST /v1/refunds`, and documents the replay-mismatch contract for them. It
+     * declares NOTHING for either buyers route. An earlier draft of this resource
+     * offered the option anyway, and that was wrong: shipping an
+     * unconfirmed safety knob on an IRREVERSIBLE, provider-propagated deletion is
+     * the wrong default — a caller would reasonably read it as the same
+     * replay-safety guarantee the other endpoints give, and we cannot back that.
+     *
+     * Removed until server support is confirmed and the API contract declares
+     * it. If you need replay safety on these calls today, guard at your own call
+     * site.
+     */
+    buyers: {
+        /**
+         * `POST /v1/buyers` — create or update a buyer.
+         *
+         * ⚠️ **This is an UPSERT.** The write is keyed on `externalId` when
+         * present, else on `email`. Calling it twice with the same key UPDATES;
+         * it does not fail with a duplicate error. The server answers `201` when it
+         * created and `200` when it updated, and the body is the full stored
+         * profile either way — so what you read back is what was persisted
+         * (including `metadata` after its append-merge).
+         *
+         * At least one of `externalId` / `email` is required: a profile with no
+         * lookup key could never be retrieved or charged against. That is checked
+         * here rather than spent on a round-trip to a `400`.
+         */
+        upsert: (params: UpsertBuyerParams) => Promise<Buyer>;
+        /**
+         * `GET /v1/buyers/:id` — fetch a stored profile by id.
+         *
+         * A cross-merchant id returns an opaque 404, never a 403.
+         */
+        retrieve: (buyerId: string) => Promise<Buyer>;
+        /**
+         * `GET /v1/buyers` — exact lookup by your reference or by email.
+         *
+         * Returns the profile or `null`. There is deliberately no unfiltered
+         * listing in v1, so at least one key is required; when both are supplied
+         * `externalId` wins, matching the upsert's identity-resolution order.
+         *
+         * Unwraps the server's `{ data: [...] }` envelope, which holds zero or one
+         * profile — handing back a one-element array to destructure would be a
+         * worse API for a lookup that can never return two.
+         */
+        find: (params: FindBuyerParams) => Promise<Buyer | null>;
+        /**
+         * `PATCH /v1/buyers/:id` — update a stored profile.
+         *
+         * Omitted fields are left unchanged. `metadata` merges with append
+         * semantics. `externalId` is not patchable — the identity key is fixed at
+         * creation; upsert a new profile instead.
+         *
+         * ⛔ **This method cannot erase.** `email` is typed `string`, so passing
+         * `null` is a compile error, and the body is built with an explicit
+         * `!== undefined` test rather than a truthiness check — a truthy test would
+         * also drop a legitimate empty-string value and, worse, would let a `null`
+         * through unnoticed if the type were ever widened. Use
+         * {@link eraseEmail} when you actually mean to erase.
+         */
+        update: (buyerId: string, params: UpdateBuyerParams) => Promise<Buyer>;
+        /**
+         * **Permanently erase this buyer's email address.** `PATCH /v1/buyers/:id`
+         * with `email: null`.
+         *
+         * It removes the address from the buyer profile. Afterwards the buyer
+         * cannot be found by email.
+         *
+         * ⚠️ **We also ASK your payment provider to drop their copy — but a
+         * successful response here does not confirm that happened.** That request
+         * is dispatched after we answer you, is never awaited, and reports no
+         * failure back: a provider error, a timeout, or an open circuit breaker
+         * all pass silently. And for a buyer we only ever knew by email, whose
+         * provider record we had not separately recorded, the retraction cannot be
+         * performed at all — the key we would need was derived from the address
+         * that was just erased. Do not tell a shopper the provider copy is gone on
+         * the strength of a `200`.
+         *
+         * ⛔ **This is NOT a complete deletion on its own, and must not be
+         * described to a shopper as one.** It clears the profile's address. Other
+         * copies live outside this record, under their own
+         * retention rules, and this call does not touch them — including the
+         * settlement record kept for financial audit, checkout sessions from the
+         * recent past, and any address already forwarded to a connected store,
+         * which is an external system with no retraction path.
+         *
+         * ⚠️ Read that as examples, **not as an inventory.** It is the set we have
+         * confirmed, not a completed audit of every place a copy can exist — your
+         * own systems may hold one we sent you earlier. Treat this call as the
+         * profile half of a deletion request, not the whole answer.
+         *
+         * ⚠️ **It cannot be undone**, and a buyer identified only by email becomes
+         * unreachable by lookup afterwards — the record and every payment attached
+         * to it survive, but `find({ email })` will no longer locate it. Keep your
+         * own reference in `externalId` if you need to find them again.
+         *
+         * No other profile field is erasable this way; `email` is the only one the
+         * API declares nullable.
+         *
+         * @returns the stored profile as it is after the erase, with `email: null`.
+         */
+        eraseEmail: (buyerId: string) => Promise<Buyer>;
+    };
     webhookSubscriptions: {
         /**
          * `GET /v1/webhook_subscriptions` — Stripe-shaped list envelope.

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -9,11 +9,34 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 const SDK_VERSION = pkg.version;
 const DEFAULT_BASE_URL = "https://checkout.vonpay.com";
-// Sent as `Von-Pay-Version` on every request. Bump alongside spec changes
-// that introduce new endpoints (e.g. SDK 0.6.x added capture/void/refunds/
-// tokens at 2026-05-05). The server treats this header as advisory routing
-// information; no SDK-side gating depends on it.
-const DEFAULT_API_VERSION = "2026-05-05";
+// Sent as `Von-Pay-Version` on every request.
+//
+// ⛔ THIS WAS "2026-05-05" AND THE API HAS NEVER ACCEPTED THAT VALUE.
+// The server keeps a one-member allowlist (`SUPPORTED_VERSIONS` in checkout's
+// proxy) containing only "2026-04-14", and silently substitutes it for anything
+// else — no error, no warning. So every request this SDK has ever sent was
+// served as 2026-04-14 while announcing something different, and the response
+// header said so.
+//
+// The old value was not a premature version. It was the DATE THE 0.6.x SDK
+// SCAFFOLD WAS WRITTEN (commit 1eb30ee, 2026-05-05), recorded as though it were
+// a contract. Nothing on the server ever implemented it; the only occurrences
+// of that string in checkout are comment dates.
+//
+// ⚠️ WHY IT MATTERED EVEN THOUGH NOTHING BROKE: a merchant copying this default
+// and pinning `Von-Pay-Version: 2026-05-05` explicitly believed they had pinned
+// a NEWER contract. They had pinned nothing and silently got the older one.
+// Version pinning that silently no-ops is the exact failure pinning exists to
+// prevent. Reported by vonpay-docs, 2026-09-08.
+//
+// This correction is RUNTIME-NEUTRAL: the server was already serving
+// 2026-04-14: only the announced value changes, to the one actually honoured.
+//
+// ⛔ Do NOT bump this to a new date because a new SDK surface shipped. It is not
+// a changelog. Bump it only when checkout ADDS the value to SUPPORTED_VERSIONS,
+// and keep it in lock-step with the Python constant
+// (`sdk/api-version-bump-both-sdks`).
+const DEFAULT_API_VERSION = "2026-04-14";
 const DEFAULT_MAX_RETRIES = 2;
 const DEFAULT_TIMEOUT = 30_000;
 const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
@@ -564,6 +587,57 @@ function toCamelKeysDeep(value) {
  * sdk/metadata-keys-opaque).
  */
 function paymentIntentFromWire(raw) {
+    const { metadata, ...rest } = raw;
+    // ⛔ `buyer.metadata` IS METADATA TOO, AND IT IS NESTED.
+    //
+    // The line below runs `toCamelKeysDeep` over everything except the TOP-LEVEL
+    // `metadata`. When `buyer` was added (2.1.0) it arrived inside `rest`, so the
+    // deep converter walked into `buyer.metadata` and renamed the merchant's own
+    // keys: `order_id` came back as `orderId`. Reproduced, not theorised — a
+    // merchant looking their own order up by the key they set would miss.
+    //
+    // That is the exact defect `sdk/metadata-keys-opaque` exists to prevent, and
+    // it reached review because the guard was written when `metadata` appeared in
+    // exactly one place. Any FUTURE nested metadata needs the same treatment —
+    // hence extracting by walking for the key rather than hardcoding `buyer`.
+    const buyerRaw = rest.buyer;
+    const buyerMetadata = buyerRaw && typeof buyerRaw === "object" ? buyerRaw.metadata : undefined;
+    const camel = toCamelKeysDeep(rest);
+    const result = {
+        ...camel,
+        metadata: metadata ?? {},
+    };
+    // Re-attach the merchant's keys byte-for-byte, after conversion.
+    if (buyerMetadata !== undefined && result.buyer) {
+        result.buyer = {
+            ...result.buyer,
+            metadata: buyerMetadata,
+        };
+    }
+    return result;
+}
+/**
+ * Parse a server buyer response into the camelCase {@link Buyer} type.
+ *
+ * ⛔ WITHOUT THIS, THE RESOURCE'S OWN PRIMARY FIELD IS UNDEFINED. `request()`
+ * returns `response.json()` raw — it does NOT convert case — and every other
+ * resource here calls a `*FromWire` helper on the way out. The first version of
+ * `buyers` called none, so `externalId`, `createdAt`, `lastSeenAt` and every
+ * nested `address.*` field came back `undefined` from a correct server
+ * response. `externalId` is the field this SDK's own erase docs tell an
+ * integrator to keep hold of.
+ *
+ * Worth recording WHY this was easy to miss:
+ * the one committed test that read a returned field read `id`, which is spelled
+ * identically in both conventions and therefore passed by coincidence. A test
+ * that only ever asserts a convention-invariant field cannot detect a
+ * conversion bug.
+ *
+ * `metadata` is passed through verbatim — integrator-defined keys must NEVER be
+ * case-converted — they are the merchant's own keys and must round-trip
+ * byte-for-byte.
+ */
+function buyerFromWire(raw) {
     const { metadata, ...rest } = raw;
     const camel = toCamelKeysDeep(rest);
     return {
@@ -1094,7 +1168,7 @@ export class VonPayCheckout {
             // (or any future regression) the property is simply absent, and a caller
             // doing an exhaustive check on a value the type says is always present
             // gets `undefined`. Python already defaults this; Node promised the same
-            // guarantee and did not enforce it (found in security review 2026-08-29).
+            // guarantee and did not enforce it (found 2026-08-29).
             //
             // Unknown or missing both resolve to `"not_tracked"`, which is the
             // fail-safe direction and the whole point of the field: it can only mean
@@ -1299,6 +1373,258 @@ export class VonPayCheckout {
      * the rest of `/v1/*` on this engine); the SDK exposes responses
      * pass-through with no key conversion.
      */
+    /**
+     * Stored shopper profiles. `vp_sk_*` Bearer required.
+     *
+     * The same profile the checkout flows write via `buyerId` / `buyerEmail`, so
+     * a buyer created here is the one a later payment attaches to.
+     *
+     * ⛔ **The erase is a separate method on purpose.** `PATCH /v1/buyers/:id`
+     * accepts `email: null` to permanently erase the address — irreversibly, and
+     * it removes the copy held at the payment provider too. The API's own docs
+     * warn that several common JSON libraries serialise absent optional fields as
+     * `null`, so an ordinary update can wipe a shopper's email with nobody
+     * intending it.
+     *
+     * This SDK refuses to expose that shape. `update()` cannot express `null` —
+     * it is a type error — and {@link eraseEmail} is the only path that sends it.
+     * An accidental erase is therefore not writable in TypeScript.
+     */
+    /**
+     * ⚠️ **No idempotency key on this resource, deliberately.**
+     *
+     * The canonical spec declares `Idempotency-Key` on `POST /v1/sessions` and
+     * `POST /v1/refunds`, and documents the replay-mismatch contract for them. It
+     * declares NOTHING for either buyers route. An earlier draft of this resource
+     * offered the option anyway, and that was wrong: shipping an
+     * unconfirmed safety knob on an IRREVERSIBLE, provider-propagated deletion is
+     * the wrong default — a caller would reasonably read it as the same
+     * replay-safety guarantee the other endpoints give, and we cannot back that.
+     *
+     * Removed until server support is confirmed and the API contract declares
+     * it. If you need replay safety on these calls today, guard at your own call
+     * site.
+     */
+    buyers = {
+        /**
+         * `POST /v1/buyers` — create or update a buyer.
+         *
+         * ⚠️ **This is an UPSERT.** The write is keyed on `externalId` when
+         * present, else on `email`. Calling it twice with the same key UPDATES;
+         * it does not fail with a duplicate error. The server answers `201` when it
+         * created and `200` when it updated, and the body is the full stored
+         * profile either way — so what you read back is what was persisted
+         * (including `metadata` after its append-merge).
+         *
+         * At least one of `externalId` / `email` is required: a profile with no
+         * lookup key could never be retrieved or charged against. That is checked
+         * here rather than spent on a round-trip to a `400`.
+         */
+        upsert: async (params) => {
+            // Snapshot before checking, for the same reason `update()` does — a
+            // getter that answers differently on a second read must not be able to
+            // change what we validated. Also means the body we send is exactly the
+            // object we inspected.
+            const snapshot = { ...(params ?? {}) };
+            if (snapshot.externalId === undefined && snapshot.email === undefined) {
+                throw new TypeError("buyers.upsert requires at least one of externalId or email — a buyer " +
+                    "with no lookup key can never be retrieved or charged against. " +
+                    "externalId is your own customer reference and is the preferred key.");
+            }
+            // ⚠️ Refuse a null email here too, even though only PATCH gives null the
+            // erase meaning. The argument for `update()`'s runtime guard — a
+            // JavaScript caller has no type system, and their serialiser may emit
+            // null for a field they left out — applies identically to this call, so
+            // guarding one and not the other would be arbitrary. The spec types
+            // this field non-nullable, so the server would answer 400; failing here
+            // with a message that names the right method is a better answer than a
+            // round-trip to a validation error.
+            if (snapshot.email === null) {
+                throw new TypeError("buyers.upsert does not accept a null email. Omit the field to leave it " +
+                    "unset, or pass an address. To erase an existing buyer's email, call " +
+                    "buyers.eraseEmail(buyerId) — that is the only method that erases.");
+            }
+            const { data } = await this.request("POST", "/v1/buyers", {
+                // buildSnakeBodyOpaqueMetadata, not toSnakeKeysDeep: the latter recurses
+                // into `metadata` and rewrites the MERCHANT'S OWN keys — `orderId`
+                // silently becomes `order_id`, which they can never match on again
+                // (review rule sdk/metadata-keys-opaque). Every other resource in this
+                // file uses the helper; buyers did not.
+                body: buildSnakeBodyOpaqueMetadata(snapshot),
+                reporterMethod: "buyers.upsert",
+            });
+            return buyerFromWire(data);
+        },
+        /**
+         * `GET /v1/buyers/:id` — fetch a stored profile by id.
+         *
+         * A cross-merchant id returns an opaque 404, never a 403.
+         */
+        retrieve: async (buyerId) => {
+            assertResourceId(buyerId, "buyerId");
+            const { data } = await this.request("GET", `/v1/buyers/${encodeURIComponent(buyerId)}`, { reporterMethod: "buyers.retrieve" });
+            return buyerFromWire(data);
+        },
+        /**
+         * `GET /v1/buyers` — exact lookup by your reference or by email.
+         *
+         * Returns the profile or `null`. There is deliberately no unfiltered
+         * listing in v1, so at least one key is required; when both are supplied
+         * `externalId` wins, matching the upsert's identity-resolution order.
+         *
+         * Unwraps the server's `{ data: [...] }` envelope, which holds zero or one
+         * profile — handing back a one-element array to destructure would be a
+         * worse API for a lookup that can never return two.
+         */
+        find: async (params) => {
+            if (params?.externalId === undefined && params?.email === undefined) {
+                throw new TypeError("buyers.find requires at least one of externalId or email — there is " +
+                    "no unfiltered buyer listing in v1.");
+            }
+            const query = {};
+            if (params.externalId !== undefined)
+                query.external_id = params.externalId;
+            if (params.email !== undefined)
+                query.email = params.email;
+            const { data } = await this.request("GET", "/v1/buyers", {
+                query,
+                reporterMethod: "buyers.find",
+            });
+            const first = data.data[0];
+            return first ? buyerFromWire(first) : null;
+        },
+        /**
+         * `PATCH /v1/buyers/:id` — update a stored profile.
+         *
+         * Omitted fields are left unchanged. `metadata` merges with append
+         * semantics. `externalId` is not patchable — the identity key is fixed at
+         * creation; upsert a new profile instead.
+         *
+         * ⛔ **This method cannot erase.** `email` is typed `string`, so passing
+         * `null` is a compile error, and the body is built with an explicit
+         * `!== undefined` test rather than a truthiness check — a truthy test would
+         * also drop a legitimate empty-string value and, worse, would let a `null`
+         * through unnoticed if the type were ever widened. Use
+         * {@link eraseEmail} when you actually mean to erase.
+         */
+        update: async (buyerId, params) => {
+            assertResourceId(buyerId, "buyerId");
+            // ⛔ REFUSE AN EXPLICIT NULL AT RUNTIME, not only in the type.
+            //
+            // The type makes this unwritable in TypeScript, and that is worth having
+            // — but it protects exactly the callers who were never the risk. The
+            // API's own warning is about JSON libraries that serialise an ABSENT
+            // optional field as `null`, and a caller in plain JavaScript has no type
+            // system at all. For both of them the type is not present at runtime and
+            // the erase would go through on an ordinary update.
+            //
+            // So the guarantee is enforced where it is actually load-bearing. There
+            // is exactly one way to erase in this SDK, and it says so in its name.
+            // ⛔ READ EVERY FIELD EXACTLY ONCE, BEFORE ANY OF THEM IS CHECKED.
+            //
+            // The first version of this guard read `params.email` three times — once
+            // to test for null, twice more to build the body. That is a
+            // check-then-use gap: an object whose `email` is a GETTER (or a Proxy)
+            // can return `undefined` to the check and `null` to the body-builder,
+            // and the erase goes through `update()` with no exception at all.
+            // Reproduced against the real code, so this is not theoretical.
+            //
+            // That is a check-then-use gap, and it defeats the entire point of the
+            // guard. Objects with lazily-evaluated properties are ordinary — ORM
+            // models, framework request binders, validation wrappers — so this needs
+            // no adversary, just a caller passing something that is not a plain
+            // object literal. Snapshot first; decide afterwards.
+            const email = params?.email;
+            const name = params?.name;
+            const phone = params?.phone;
+            const company = params?.company;
+            const address = params?.address;
+            const metadata = params?.metadata;
+            if (email === null) {
+                throw new TypeError("buyers.update cannot erase an email address. Sending `email: null` on " +
+                    "this endpoint permanently erases it — including the copy held at your " +
+                    "payment provider — and it cannot be undone. If you meant to erase it, " +
+                    "call buyers.eraseEmail(buyerId). If you did not, check whether your " +
+                    "JSON serialiser is emitting null for fields you simply left out; " +
+                    "several common libraries do that by default. To leave the address " +
+                    "unchanged, omit the field entirely.");
+            }
+            const patch = {};
+            // Explicit `!== undefined`, never truthiness: "" is a legitimate value to
+            // send for a name, and truthiness would silently drop it.
+            if (email !== undefined)
+                patch.email = email;
+            if (name !== undefined)
+                patch.name = name;
+            if (phone !== undefined)
+                patch.phone = phone;
+            if (company !== undefined)
+                patch.company = company;
+            if (address !== undefined)
+                patch.address = address;
+            if (metadata !== undefined)
+                patch.metadata = metadata;
+            // Same helper as every other resource: snake-cases `address.addressLine1`
+            // and friends while leaving the merchant's own metadata keys untouched.
+            const body = buildSnakeBodyOpaqueMetadata(patch);
+            const { data } = await this.request("PATCH", `/v1/buyers/${encodeURIComponent(buyerId)}`, {
+                body,
+                reporterMethod: "buyers.update",
+            });
+            return buyerFromWire(data);
+        },
+        /**
+         * **Permanently erase this buyer's email address.** `PATCH /v1/buyers/:id`
+         * with `email: null`.
+         *
+         * It removes the address from the buyer profile. Afterwards the buyer
+         * cannot be found by email.
+         *
+         * ⚠️ **We also ASK your payment provider to drop their copy — but a
+         * successful response here does not confirm that happened.** That request
+         * is dispatched after we answer you, is never awaited, and reports no
+         * failure back: a provider error, a timeout, or an open circuit breaker
+         * all pass silently. And for a buyer we only ever knew by email, whose
+         * provider record we had not separately recorded, the retraction cannot be
+         * performed at all — the key we would need was derived from the address
+         * that was just erased. Do not tell a shopper the provider copy is gone on
+         * the strength of a `200`.
+         *
+         * ⛔ **This is NOT a complete deletion on its own, and must not be
+         * described to a shopper as one.** It clears the profile's address. Other
+         * copies live outside this record, under their own
+         * retention rules, and this call does not touch them — including the
+         * settlement record kept for financial audit, checkout sessions from the
+         * recent past, and any address already forwarded to a connected store,
+         * which is an external system with no retraction path.
+         *
+         * ⚠️ Read that as examples, **not as an inventory.** It is the set we have
+         * confirmed, not a completed audit of every place a copy can exist — your
+         * own systems may hold one we sent you earlier. Treat this call as the
+         * profile half of a deletion request, not the whole answer.
+         *
+         * ⚠️ **It cannot be undone**, and a buyer identified only by email becomes
+         * unreachable by lookup afterwards — the record and every payment attached
+         * to it survive, but `find({ email })` will no longer locate it. Keep your
+         * own reference in `externalId` if you need to find them again.
+         *
+         * No other profile field is erasable this way; `email` is the only one the
+         * API declares nullable.
+         *
+         * @returns the stored profile as it is after the erase, with `email: null`.
+         */
+        eraseEmail: async (buyerId) => {
+            assertResourceId(buyerId, "buyerId");
+            const { data } = await this.request("PATCH", `/v1/buyers/${encodeURIComponent(buyerId)}`, {
+                // The one place in this SDK that sends an explicit null. Written as a
+                // literal rather than routed through the params builder so it cannot
+                // be reached by any other call path.
+                body: { email: null },
+                reporterMethod: "buyers.eraseEmail",
+            });
+            return buyerFromWire(data);
+        },
+    };
     webhookSubscriptions = {
         /**
          * `GET /v1/webhook_subscriptions` — Stripe-shaped list envelope.