@usdctofiat/offramp 1.3.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,252 @@
+# Changelog
+
+All notable changes to `@usdctofiat/offramp` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [2.0.0] - 2026-04-24
+
+### ⚠ BREAKING CHANGES
+
+The upstream zkp2p-clients protocol cut curator's maker registration over to a
+new schema and endpoint, and now requires Peer browser-extension
+pre-registration for PayPal and Wise makers. Previous versions of this SDK
+were silently broken against the live API. Upgrading is **mandatory** for any
+integrator still on `1.x` — the old payload shape is rejected by curator.
+
+- **Endpoint**: maker registration now hits `POST /v2/makers/create`
+  (upstream commit 3243ce5). `/v1/makers/create` is gone.
+- **Payload shape**: `buildDepositData(platform, identifier, telegramUsername?)`
+  now returns `{ offchainId, telegramUsername? }` instead of legacy
+  platform-specific blobs like `{ paypalEmail, venmoUsername, wisetag, … }`
+  (upstream commit e4e5bdd / PR #580). Curator hashes `offchainId + processorName`
+  directly, so the old keys are no longer read.
+- **PayPal identifier**: PayPal deposits now use the PayPal.me username as the
+  offchainId, not the account email (upstream #649). `PLATFORMS.PAYPAL.validate(...)`
+  rejects emails and accepts `paypal.me/user`, `@user`, or the bare username,
+  all normalized to a lowercase `paypal.me` username.
+- **New error code**: `OFFRAMP_ERROR_CODES.EXTENSION_REGISTRATION_REQUIRED`.
+  `offramp()` throws this when curator rejects a PayPal or Wise maker because
+  the user has not yet registered their handle inside the Peer (PeerAuth)
+  browser extension. Recover via `usePeerExtensionRegistration(platform)` (React)
+  or drive `peerExtensionSdk` manually, then retry the call.
+
+### Added
+
+- **Extension handshake helpers** (core entry point):
+  - `peerExtensionSdk`, `PEER_EXTENSION_CHROME_URL`, `getPeerExtensionState`,
+    `isPeerExtensionAvailable`, `openPeerExtensionInstallPage`,
+    `createPeerExtensionSdk` — re-exports from `@zkp2p/sdk` so integrators
+    don't need a direct transitive dependency on it.
+  - Types: `PeerExtensionApi`, `PeerExtensionSdk`, `PeerExtensionSdkOptions`,
+    `PeerExtensionState`, `PeerExtensionWindow`, `PeerConnectionStatus`.
+- **React hook** `usePeerExtensionRegistration(platform)` in
+  `@usdctofiat/offramp/react`. Drives the full install → connect → verify
+  flow with a phase state machine (`checking | needs_install | needs_connection | ready | unsupported`),
+  auto-invoking `requestConnection()` and `openSidebar('/verify/<providerId>')`
+  in response to `peerExtensionSdk.getState()`.
+- **Platform metadata**: `PLATFORMS.PAYPAL.extensionRegistration` and
+  `PLATFORMS.WISE.extensionRegistration` surface the `providerId`, user-facing
+  prompt, CTA copy, and minimum extension version. Access via
+  `getPeerExtensionRegistrationInfo(platformId)`.
+- **Error detection helper**: `isPeerExtensionRegistrationError(platformId, message, statusCode)`
+  returns true when a failed `/v2/makers/create` response should be treated as
+  "maker needs extension registration". Mirrors the upstream heuristic
+  (400 status on a registration-required platform, or any response whose
+  message contains `creating the maker` / `create the maker`).
+- **MakersCreateError**: thrown by the internal maker-registration fetch,
+  preserving the HTTP status and raw response body so callers can inspect the
+  failure. Re-raised by `offramp()` as the `cause` on the surfaced `OfframpError`.
+- **PayPal.me normalizer**: `normalizePaypalMeUsername(input)` exported for
+  integrators that want to normalize user input before hashing or display.
+- **`PayeeDepositData`** type (the flat shape returned by `buildDepositData`).
+
+### Changed
+
+- `PLATFORMS.PAYPAL.identifier` updated to username semantics (`label: "PayPal.me Username"`,
+  `placeholder: "paypal.me/your-username"`, `help: "Your PayPal.me username, not your email"`).
+- `PLATFORMS.PAYPAL.validate(...)` enforces `[a-z0-9._-]+` and lowercases the
+  normalized value.
+- `PLATFORMS.WISE` now ships `extensionRegistration` metadata (no prompt change
+  for the happy path).
+
+### Migration guide
+
+If you were on `@usdctofiat/offramp@1.x`:
+
+1. Upgrade to `2.0.0`.
+2. For PayPal integrations, re-prompt users for their PayPal.me username
+   (not email). You can round-trip legacy emails through
+   `PLATFORMS.PAYPAL.validate(email)` to detect them — invalid input signals
+   the user needs to re-enter.
+3. Handle the new `EXTENSION_REGISTRATION_REQUIRED` error. Minimum example
+   with the React hook:
+
+   ```tsx
+   import { PLATFORMS, OFFRAMP_ERROR_CODES } from "@usdctofiat/offramp";
+   import { useOfframp, usePeerExtensionRegistration } from "@usdctofiat/offramp/react";
+
+   const { offramp, lastError } = useOfframp();
+   const peer = usePeerExtensionRegistration(PLATFORMS.PAYPAL);
+
+   if (lastError?.code === OFFRAMP_ERROR_CODES.EXTENSION_REGISTRATION_REQUIRED) {
+     // Render peer.phase-aware CTAs using peer.installExtension /
+     // peer.connectExtension / peer.openVerifySidebar, then call offramp() again.
+   }
+   ```
+
+4. If you hand-rolled a `POST /v1/makers/create` call, switch to
+   `POST /v2/makers/create` with `{ processorName, offchainId, telegramUsername? }`.
+
+## [1.3.0] - 2026-04-21
+
+### Removed
+
+- Widget entry point. The `@usdctofiat/offramp/widget` subpath and its exports (`OfframpButton`, `OfframpInline`, `OfframpDrawer`), plus the `sdk.widget.view` / `sdk.widget.click` telemetry events. Call `offramp(...)` directly or use `useOfframp` from `@usdctofiat/offramp/react`. The `create-offramp-app` templates were updated to the plain-function flow.
+
+## [1.2.0] - 2026-04-21
+
+### Added
+
+- Widget entry point at `@usdctofiat/offramp/widget` with `OfframpButton`, `OfframpInline`, `OfframpDrawer` components and `sdk.widget.*` telemetry events. Reverted in 1.3.0.
+- Anonymous SDK usage telemetry (`sdk.deposit.*`) written to Firestore. Opt out via `new Offramp({ telemetry: false })`.
+
+### Changed
+
+- `viem` moved from a direct dependency to a peer dependency so consumers share a single `viem` copy with the SDK, preventing duplicate-module `WalletClient` type clashes.
+
+## [1.1.4] - 2026-04-16
+
+### Fixed
+
+- Case-insensitive `rateManagerId` comparison when matching delegated deposits.
+
+## [1.1.3] - 2026-04-09
+
+### Changed
+
+- Bump `@zkp2p/sdk` to `0.3.1`. Picks up the curator API migration: the SDK now targets `/v3/intent/sign` (the legacy `/v3/intent` path is still aliased but scheduled for removal on 2026-07-01) and the maker schema is now flat (`offchainId` + `telegramUsername` columns). Transparent to SDK consumers.
+
+## [1.1.2] - 2026-04-06
+
+### Fixed
+
+- Widen `viem` dependency from exact `2.45.3` to `^2.45.0`. The exact pin introduced in 1.1.1 forced npm to install a nested copy of `viem` whenever the consumer had any other `viem` version, causing TypeScript `Client is not assignable to Client` errors at the SDK boundary (two structurally identical but distinct module copies).
+
+## [1.1.1] - 2026-04-05
+
+### Fixed
+
+- Updated `WhitelistPreIntentHook` address to the redeployed contract. The old hook reverted on OTC intent fulfillment via `OrchestratorV2`.
+
+## [1.1.0] - 2026-04-03
+
+### Added
+
+- OTC private orders: restrict a deposit to a single taker wallet.
+  - `otcTaker` parameter on `offramp()` for one-call OTC deposit creation.
+  - `enableOtc(walletClient, depositId, takerAddress)` to restrict an existing deposit.
+  - `disableOtc(walletClient, depositId)` to make a deposit public again.
+  - `getOtcLink(depositId)` returns the taker URL without a transaction.
+- `OfframpResult.otcLink` returned when `otcTaker` is provided.
+- `"restricting"` step added to `OfframpStep` for progress callbacks.
+
+## [1.0.1] - 2026-03-29
+
+### Fixed
+
+- Resume the most recent undelegated deposit first when a wallet has multiple in flight.
+
+## [1.0.0] - 2026-03-29
+
+### Changed
+
+- Minimal surface refactor. The public API is now the `Offramp` class plus `offramp()` function (core) and `useOfframp` (React). This is the first stable release.
+
+### Removed
+
+- Pre-1.0 surface area not carried forward. Integrators on 0.2.x should migrate to the new API.
+
+## [0.2.1] - 2026-03-29
+
+### Fixed
+
+- Use `defaultIndexerEndpoint` for read-only indexer queries so SDK reads work without additional configuration.
+
+## [0.2.0] - 2026-03-29
+
+### Added
+
+- Structured errors (`OfframpError` with `code`, `step`, `txHash`, `depositId`).
+- Deposit recovery: the SDK resumes the most recent undelegated deposit for a wallet instead of creating a new one.
+
+### Fixed
+
+- Indexer endpoint resolution.
+
+## [0.1.5] - 2026-03-29
+
+### Added
+
+- `delegateDeposit()` for retrying delegation or delegating an existing deposit.
+
+## [0.1.4] - 2026-03-29
+
+### Added
+
+- Typed constant maps for platforms and currencies.
+- Currency metadata (symbol, decimals, display name).
+
+## [0.1.3] - 2026-03-29
+
+### Added
+
+- Pre-flight USDC balance check before submitting a deposit.
+- Amount truncation to USDC decimals.
+- Wallet validation on deposit inputs.
+
+## [0.1.2] - 2026-03-29
+
+### Changed
+
+- Reduced minimum deposit and minimum order to 1 USDC.
+
+## [0.1.1] - 2026-03-29
+
+### Fixed
+
+- Resolve currency hashes to ISO codes in error messages and responses.
+- Improved error messages for invalid currency and platform inputs.
+
+## [0.1.0] - 2026-03-29
+
+### Added
+
+- Initial release of `@usdctofiat/offramp`.
+- `Offramp` class and `offramp()` function for creating delegated USDC-to-fiat deposits on Base.
+- `useOfframp` React hook (`@usdctofiat/offramp/react`).
+- `getDeposits`, `withdrawDeposit`, `getPlatforms`, `validateIdentifier` helpers.
+- All deposits automatically delegate to the Delegate vault, use `track_market` pricing, and carry Galleon Labs attribution.
+- Dual CJS/ESM build via tsup with type definitions for both entry points.
+
+[Unreleased]: https://github.com/ADWilkinson/galleonlabs-zkp2p/compare/main...HEAD
+[1.3.0]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v1.3.0
+[1.2.0]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v1.2.0
+[1.1.4]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v1.1.4
+[1.1.3]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v1.1.3
+[1.1.2]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v1.1.2
+[1.1.1]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v1.1.1
+[1.1.0]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v1.1.0
+[1.0.1]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v1.0.1
+[1.0.0]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v1.0.0
+[0.2.1]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v0.2.1
+[0.2.0]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v0.2.0
+[0.1.5]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v0.1.5
+[0.1.4]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v0.1.4
+[0.1.3]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v0.1.3
+[0.1.2]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v0.1.2
+[0.1.1]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v0.1.1
+[0.1.0]: https://github.com/ADWilkinson/galleonlabs-zkp2p/releases/tag/offramp-sdk-v0.1.0

package/README.md

@@ -111,22 +111,102 @@ getOtcLink("362"); // just the URL, no tx
 ## Error Handling
 
 ```typescript
-import { OfframpError } from "@usdctofiat/offramp";
+import { OfframpError, OFFRAMP_ERROR_CODES } from "@usdctofiat/offramp";
 
 try {
   await offramp(walletClient, params);
 } catch (err) {
   if (err instanceof OfframpError) {
     if (err.code === "USER_CANCELLED") return;
-    // For any failure: call offramp() again to resume
+    if (err.code === OFFRAMP_ERROR_CODES.EXTENSION_REGISTRATION_REQUIRED) {
+      // User needs to register in the Peer extension first — see below.
+      return;
+    }
+    // For any other failure: call offramp() again to resume
   }
 }
 ```
 
+## Peer Extension Registration (PayPal, Wise)
+
+PayPal and Wise makers must register their handle inside the Peer (PeerAuth)
+browser extension before the first deposit. The SDK throws `OfframpError`
+with code `EXTENSION_REGISTRATION_REQUIRED` when curator rejects a maker for
+this reason. Drive the three-step handshake via the React hook:
+
+```tsx
+import { PLATFORMS, CURRENCIES, OFFRAMP_ERROR_CODES } from "@usdctofiat/offramp";
+import { useOfframp, usePeerExtensionRegistration } from "@usdctofiat/offramp/react";
+
+function PayPalSellButton({ walletClient }) {
+  const { offramp, lastError } = useOfframp();
+  const peer = usePeerExtensionRegistration(PLATFORMS.PAYPAL);
+
+  const needsExtension = lastError?.code === OFFRAMP_ERROR_CODES.EXTENSION_REGISTRATION_REQUIRED;
+
+  return (
+    <>
+      <button
+        onClick={() =>
+          offramp(walletClient, {
+            amount: "100",
+            platform: PLATFORMS.PAYPAL,
+            currency: CURRENCIES.USD,
+            identifier: "alicepay", // PayPal.me username, NOT email
+          })
+        }
+      >
+        Sell USDC
+      </button>
+
+      {needsExtension && (
+        <div>
+          <p>{peer.info?.requiredPrompt}</p>
+          {peer.phase === "needs_install" && (
+            <button onClick={peer.installExtension}>Install Peer Extension</button>
+          )}
+          {peer.phase === "needs_connection" && (
+            <button onClick={peer.connectExtension} disabled={peer.busy}>
+              Connect Peer Extension
+            </button>
+          )}
+          {peer.phase === "ready" && (
+            <button onClick={peer.openVerifySidebar}>Verify in Peer</button>
+          )}
+          {peer.info?.ctaSubtext && <small>{peer.info.ctaSubtext}</small>}
+        </div>
+      )}
+    </>
+  );
+}
+```
+
+Or drive the handshake manually via `peerExtensionSdk`:
+
+```typescript
+import { peerExtensionSdk } from "@usdctofiat/offramp";
+
+const state = await peerExtensionSdk.getState();
+if (state === "needs_install") {
+  peerExtensionSdk.openInstallPage();
+} else if (state === "needs_connection") {
+  const approved = await peerExtensionSdk.requestConnection();
+  if (approved) peerExtensionSdk.openSidebar("/verify/paypal");
+} else {
+  peerExtensionSdk.openSidebar("/verify/paypal");
+}
+```
+
+After the user completes the flow in the extension, call `offramp()` again.
+
 ## How It Works
 
 Every deposit is automatically delegated to the Delegate vault for oracle-based rate management, auto-closes when filled, and is attributed to Galleon Labs via ERC-8021.
 
+## Webhooks
+
+Subscribe to `deposit.created`, `deposit.filled`, `deposit.partially_filled`, `deposit.closed`, `otc.enabled`, `otc.disabled`, and `otc.taken` events for your attributed deposits. Register endpoints at [usdctofiat.xyz/developers](https://usdctofiat.xyz/developers) with your Peerlytics API key. HMAC-SHA256 signed deliveries use the `X-Usdctofiat-Signature: t=<unix>,v1=<hex>` header. Reference HMAC receiver in the [starters repo](https://github.com/ADWilkinson/usdctofiat-peerlytics-starters).
+
 ## Links
 
 [usdctofiat.xyz](https://usdctofiat.xyz) · [delegate.usdctofiat.xyz](https://delegate.usdctofiat.xyz) · [peerlytics.xyz](https://peerlytics.xyz) · [orderbook.peerlytics.xyz](https://orderbook.peerlytics.xyz)

package/dist/{chunk-JQBKGGI2.js → chunk-HBR3Z6HX.js}

@@ -122,6 +122,17 @@ function resolveSupportedCurrencies(platform) {
   }
   return Array.from(codes).sort();
 }
+function normalizePaypalMeUsername(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+  const withoutProtocol = trimmed.replace(/^https?:\/\//i, "").replace(/^www\./i, "");
+  if (/^paypal\.me(?:[?#].*)?$/i.test(withoutProtocol)) return "";
+  const withoutDomain = withoutProtocol.replace(/^paypal\.me\//i, "");
+  const [pathWithoutQuery] = withoutDomain.split(/[?#]/, 1);
+  const sanitizedPath = pathWithoutQuery.replace(/^\/+/, "");
+  const [username] = sanitizedPath.split("/", 1);
+  return username.replace(/^@+/, "").trim().toLowerCase();
+}
 var BLUEPRINTS = {
   venmo: {
     id: "venmo",
@@ -169,7 +180,13 @@ var BLUEPRINTS = {
     placeholder: "wisetag (no @)",
     helperText: "Your Wise @wisetag (no @)",
     validation: z.string().min(1).regex(/^[a-zA-Z0-9_-]+$/),
-    transform: (v) => v.replace(/^@+/, "").trim()
+    transform: (v) => v.replace(/^@+/, "").trim(),
+    extensionRegistration: {
+      providerId: "wise",
+      requiredPrompt: "This Wisetag is not registered yet. Verify it in the Peer extension, then refresh and retry with the same Wisetag.",
+      ctaLabel: "Install Peer Extension",
+      minExtensionVersion: "0.4.12"
+    }
   },
   mercadopago: {
     id: "mercadopago",
@@ -190,10 +207,18 @@ var BLUEPRINTS = {
   paypal: {
     id: "paypal",
     name: "PayPal",
-    identifierLabel: "Email",
-    placeholder: "email",
-    helperText: "Email linked to PayPal account",
-    validation: z.string().email()
+    identifierLabel: "PayPal.me Username",
+    placeholder: "paypal.me/your-username",
+    helperText: "Your PayPal.me username, not your email",
+    validation: z.string().min(1, "PayPal.me username is required").regex(/^[a-z0-9._-]+$/i, "Use your PayPal.me username (letters, numbers, . _ -)"),
+    transform: normalizePaypalMeUsername,
+    extensionRegistration: {
+      providerId: "paypal",
+      requiredPrompt: "This PayPal username is not registered yet. Verify it in the Peer extension, then refresh and retry with the same PayPal username.",
+      ctaLabel: "Install Peer Extension",
+      ctaSubtext: "PayPal Business accounts are not supported at this time.",
+      minExtensionVersion: "0.4.14"
+    }
   },
   monzo: {
     id: "monzo",
@@ -224,6 +249,7 @@ function buildPlatformEntry(bp) {
       placeholder: bp.placeholder,
       help: bp.helperText
     },
+    ...bp.extensionRegistration ? { extensionRegistration: bp.extensionRegistration } : {},
     validate(input) {
       const transformed = bp.transform ? bp.transform(input) : input;
       const result = bp.validation.safeParse(transformed);
@@ -250,6 +276,9 @@ var PLATFORMS = {
   MONZO: buildPlatformEntry(BLUEPRINTS.monzo),
   N26: buildPlatformEntry(BLUEPRINTS.n26)
 };
+function getPlatformById(id) {
+  return Object.values(PLATFORMS).find((p) => p.id === id) ?? null;
+}
 function normalizePaymentMethodLookupName(platform) {
   const normalized = platform.trim().toLowerCase();
   if (!normalized) return null;
@@ -293,34 +322,37 @@ function getPaymentMethodHashes(platform) {
   }
   return Array.from(hashes);
 }
-function buildDepositData(platform, identifier) {
-  switch (platform) {
-    case "venmo":
-      return { venmoUsername: identifier, telegramUsername: "" };
-    case "cashapp":
-      return { cashtag: identifier, telegramUsername: "" };
-    case "chime":
-      return { chimesign: identifier.toLowerCase(), telegramUsername: "" };
-    case "revolut":
-      return { revolutUsername: identifier, telegramUsername: "" };
-    case "wise":
-      return { wisetag: identifier, telegramUsername: "" };
-    case "mercadopago":
-      return { cvu: identifier, telegramUsername: "" };
-    case "zelle":
-      return { zelleEmail: identifier, telegramUsername: "" };
-    case "paypal":
-      return { paypalEmail: identifier, telegramUsername: "" };
-    case "monzo":
-      return { monzoMeUsername: identifier, telegramUsername: "" };
-    case "n26":
-      return { iban: identifier, telegramUsername: "" };
-    default:
-      return { identifier, telegramUsername: "" };
-  }
+function buildDepositData(platform, identifier, telegramUsername = "") {
+  const offchainId = platform === "chime" ? identifier.toLowerCase() : identifier;
+  return telegramUsername ? { offchainId, telegramUsername } : { offchainId };
+}
+function getPeerExtensionRegistrationInfo(platform) {
+  const entry = getPlatformById(platform);
+  return entry?.extensionRegistration ?? null;
+}
+var EXTENSION_REGISTRATION_ERROR_PATTERNS = ["creating the maker", "create the maker"];
+function isPeerExtensionRegistrationError(platform, message, statusCode) {
+  const info = getPeerExtensionRegistrationInfo(platform);
+  if (!info) return false;
+  const normalized = (message ?? "").trim();
+  if (normalized === info.requiredPrompt) return true;
+  if (statusCode === 400) return true;
+  if (!normalized) return false;
+  const lower = normalized.toLowerCase();
+  return EXTENSION_REGISTRATION_ERROR_PATTERNS.some((p) => lower.includes(p));
 }
 
 // src/errors.ts
+var MakersCreateError = class extends Error {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.name = "MakersCreateError";
+    this.status = status;
+    this.body = body;
+  }
+};
 var OfframpError = class extends Error {
   code;
   step;
@@ -1122,23 +1154,39 @@ function extractDepositIdFromLogs(logs) {
   }
   return null;
 }
-async function registerPayeeDetails(processorName, depositData) {
+async function registerPayeeDetails(processorName, payload) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), PAYEE_REGISTRATION_TIMEOUT_MS);
   try {
-    const res = await fetch(`${API_BASE_URL}/v1/makers/create`, {
+    const res = await fetch(`${API_BASE_URL}/v2/makers/create`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ processorName, depositData }),
+      body: JSON.stringify({ processorName, ...payload }),
       signal: controller.signal
     });
     if (!res.ok) {
       const txt = await res.text().catch(() => "");
-      throw new Error(`makers/create failed (${res.status}): ${txt || res.statusText}`);
+      let detail = txt || res.statusText;
+      try {
+        const parsed = JSON.parse(txt);
+        if (typeof parsed.message === "string" && parsed.message.trim()) {
+          detail = parsed.message;
+        }
+      } catch {
+      }
+      throw new MakersCreateError(
+        `makers/create failed (${res.status}): ${detail}`,
+        res.status,
+        txt
+      );
     }
     const json = await res.json();
     if (!json.success || !json.responseObject?.hashedOnchainId) {
-      throw new Error(json.message || "makers/create returned no hashedOnchainId");
+      throw new MakersCreateError(
+        json.message || "makers/create returned no hashedOnchainId",
+        json.statusCode ?? null,
+        ""
+      );
     }
     return json.responseObject.hashedOnchainId;
   } finally {
@@ -1340,11 +1388,21 @@ async function offramp(walletClient, params, onProgress, telemetryContext) {
     }
     emitProgress({ step: "registering" });
     let hashedOnchainId;
+    const canonicalName = platformId.startsWith("zelle") ? "zelle" : platformId;
     try {
-      const canonicalName = platformId.startsWith("zelle") ? "zelle" : platformId;
-      const depositData = buildDepositData(platformId, normalizedIdentifier);
-      hashedOnchainId = await registerPayeeDetails(canonicalName, depositData);
+      const payeePayload = buildDepositData(canonicalName, normalizedIdentifier);
+      hashedOnchainId = await registerPayeeDetails(canonicalName, payeePayload);
     } catch (err) {
+      const status = err instanceof MakersCreateError ? err.status : null;
+      const message = err instanceof Error ? err.message : String(err);
+      if (isPeerExtensionRegistrationError(canonicalName, message, status)) {
+        throw new OfframpError(
+          `${platform.name} maker is not yet registered in the Peer extension. Verify this handle in the extension, then retry.`,
+          "EXTENSION_REGISTRATION_REQUIRED",
+          "registering",
+          err
+        );
+      }
       throw new OfframpError(
         "Payee registration failed",
         "REGISTRATION_FAILED",
@@ -1677,9 +1735,23 @@ function createOfframp(options) {
   return new Offramp(options);
 }
 
+// src/extension.ts
+import {
+  PEER_EXTENSION_CHROME_URL,
+  peerExtensionSdk,
+  createPeerExtensionSdk,
+  isPeerExtensionAvailable,
+  openPeerExtensionInstallPage,
+  getPeerExtensionState
+} from "@zkp2p/sdk";
+
 export {
   ESCROW_ADDRESS,
+  normalizePaypalMeUsername,
   PLATFORMS,
+  getPeerExtensionRegistrationInfo,
+  isPeerExtensionRegistrationError,
+  MakersCreateError,
   OfframpError,
   enableOtc,
   disableOtc,
@@ -1695,6 +1767,12 @@ export {
   offramp,
   CURRENCIES,
   Offramp,
-  createOfframp
+  createOfframp,
+  PEER_EXTENSION_CHROME_URL,
+  peerExtensionSdk,
+  createPeerExtensionSdk,
+  isPeerExtensionAvailable,
+  openPeerExtensionInstallPage,
+  getPeerExtensionState
 };
-//# sourceMappingURL=chunk-JQBKGGI2.js.map
+//# sourceMappingURL=chunk-HBR3Z6HX.js.map