@usdctofiat/offramp 1.1.4 → 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)