@swype-org/deposit 0.3.26 → 0.3.32

package/README.md

@@ -99,6 +99,7 @@ const deposit = new Deposit({
   signerTimeoutMs: 15_000,
   flowTimeoutMs: 300_000,
   enableFullWidget: true,
+  presentation: 'overlay',   // or 'embedded' — see below
   debug: false,
 });
 ```
@@ -112,6 +113,174 @@ has it enabled — disabling either turns it off. Set it to `false` to force the
 hosted flow straight to the standard deposit flow regardless of merchant
 config.
 
+## Embedded presentation (payment-method aggregators)
+
+By default Blink opens as a full-screen modal: a dim + blur backdrop with the
+payment card centered on top. If you're a payment-method aggregator listing
+Blink as one option **inside your own widget**, set
+`presentation: 'embedded'` and Blink renders inline in an element you provide —
+no backdrop, no page scroll lock, no Escape/backdrop dismissal (all of that
+stays yours), and chrome-less so your panel owns the radius, background and
+shadow.
+
+```typescript
+// On widget mount. `slot` is an empty <div> inside your method panel.
+const deposit = new Deposit({
+  signer: '/api/sign-payment',
+  merchantId: MERCHANT_ID,
+  presentation: 'embedded',
+  containerElement: slot,      // required
+  embedMaxHeightPx: 640,       // your panel's height budget
+});
+
+// Blink reports its rendered height; the SDK has already resized the iframe.
+// Follow it to size your own panel — height with NO transition (see below).
+deposit.on('resize', ({ heightPx, preferredWidthPx, minWidthPx }) => {
+  panel.style.height = `${heightPx}px`;
+  // Optional: size the panel's width to the flow too. These are constants
+  // (440 / 320), not measurements, so they are safe to transition.
+  panel.style.width = `${preferredWidthPx}px`;
+});
+
+// When the user picks the Blink row:
+try {
+  const { transfer } = await deposit.requestDeposit({ amount, chainId, address, token });
+} catch (err) {
+  if (err instanceof DepositError && err.code === 'DEPOSIT_DISMISSED') {
+    showMethodList();          // user backed out of Blink
+  }
+}
+
+deposit.close();               // your own back button
+deposit.destroy();             // widget unmount
+```
+
+`close()` rejects the pending `requestDeposit()` with `DEPOSIT_DISMISSED` — the
+same code the flow's own close control uses — so the `catch` above is the single
+place you restore your method list. (It reports no `error` event and leaves
+`status` on `'idle'`: you asked for this one.)
+
+Three things to get right:
+
+- **`containerElement` is required, must be stable across re-renders, and must
+  never be hidden with `display: none`.** Moving an iframe in the DOM reloads it,
+  throwing away the warm-up and the user's session — so render the slot once and
+  never recreate the node. When another method is selected, hide it *without
+  removing its layout*:
+
+  ```css
+  /* the Blink slot while another method is showing */
+  visibility: hidden; height: 0; overflow: hidden; pointer-events: none;
+  ```
+
+  `display: none` looks equivalent and is not: that subtree has no layout, so the
+  flow Blink re-warms into it after every close cannot measure itself and may
+  report no height at all. The panel then reopens blank at its budget height with
+  nothing in your console. It is timing-dependent, which is what makes it nasty —
+  closing your whole dialog tends to flip `display` in the same commit and works,
+  while a back button inside the panel does not. The SDK warns when it reveals
+  into an unrendered container; that warning is this.
+- **Don't add a CSS transition to the height you get from `resize`.** Blink
+  animates its own height over ~300ms and reports every frame of it. A
+  transition on your side makes the panel chase each of those frames, so it
+  keeps moving after the content has settled — which shifts elements under the
+  pointer and shows up as the cursor flickering between pointer and default.
+  Apply the height directly. `preferredWidthPx` is a constant, so transitioning
+  the *width* is fine.
+- **Embedded is a desktop presentation.** On mobile the same config presents as
+  Blink's normal full-screen sheet, because a phone-sized method panel cannot
+  hold a flow with a keypad, wallet lists, a QR code and a passkey ceremony.
+  Nothing else downgrades it: no failure in the hosted flow will drop a modal
+  over your app unannounced. Read the resolved value from `deposit.presentation`
+  (`'overlay' | 'embedded'`) — on `'overlay'` no `resize` event ever fires, so
+  collapse or skip the slot rather than leaving an empty box behind the sheet:
+
+  ```typescript
+  // Re-read on resize; it is live until Blink builds its warm-up frame.
+  {deposit.presentation === 'embedded' && <MethodPanel />}
+  ```
+
+### Brand colors
+
+Five colors, and Blink derives its whole palette from them — surfaces, the
+recessed and hover steps, the text ramp, borders, the button hover and label, the
+tinted semantic surfaces — so the flow reads as part of your product rather than a
+foreign panel inside it. Names follow Stripe's `appearance.variables`.
+
+```typescript
+const deposit = new Deposit({
+  signer: '/api/sign-payment',
+  presentation: 'embedded',
+  containerElement: slot,
+  appearance: {
+    theme: 'light',
+    variables: {
+      colorPrimary: '#0f62fe',      // primary button, focus ring, selected states
+      colorBackground: '#101828',   // the card surface
+      colorText: '#f7f9fc',
+      colorDanger: '#ff5c5c',       // optional
+      colorBorder: '#22304a',       // optional — derived from surface + text if omitted
+    },
+  },
+});
+```
+
+Worth knowing before you pick values:
+
+- **Opaque hex only** (`#rgb` or `#rrggbb`). `rgb()`, CSS color names and 8-digit
+  hex with alpha are dropped with a console error naming the key — a solid card
+  cannot honour translucency, and an unparseable color cannot be contrast-checked.
+- **`colorBackground` picks the light or dark base** for everything that is not
+  themeable (shadows, the scrim, semantic hues), by its own luminance. A dark
+  surface stays coherent even with `theme: 'light'`.
+- **Contrast is enforced.** Where a derived pair would fall below WCAG AA the
+  *derived* value is substituted — never your input — and the substitution is
+  reported in the hosted flow's console. A `colorPrimary` too mid-toned for either
+  a black or a white label is reported and left alone; only you can fix that one.
+- **Not themeable:** the type scale, weights, radii, fonts, Blink's own marks, and
+  the success/error/warning hues and authorization states.
+
+Everything else derives, deliberately: the palette has ~35 mutually-constrained
+tokens and five inputs cannot produce a broken combination, where thirty-five
+reliably would.
+
+`embedMaxHeightPx` (default: 90% of the host viewport) caps the iframe and is
+also the basis Blink sizes its own layout against. Past that height the flow
+scrolls internally instead of growing your panel.
+
+Blink's screens are designed for **320–440px wide**, and the flow reports that
+envelope on every `resize` as `minWidthPx` (320) and `preferredWidthPx` (440).
+The iframe fills the width you give it, capped at 440 — it cannot widen your
+panel on its own, so if you want the panel to fit the flow, size it from
+`preferredWidthPx`. Below `minWidthPx`, fixed-width elements inside the flow
+overflow.
+
+Your CSP needs `frame-src https://pay.blink.cash`.
+
+### Merchant balance
+
+If your users hold a balance on your platform, pass it on the request and the
+flow shows it under the deposit header — "Acme balance: $20.70" — so the user
+tops up with their number in view:
+
+```typescript
+await deposit.requestDeposit({
+  amount: null,
+  chainId: 8453,
+  address: userWalletAddress,
+  token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+  balance: 20.7,            // USD — display only
+});
+```
+
+Display-only by design: the value is never part of the signed payload and never
+reaches your signer, so no signer changes are needed — and it cannot affect the
+transfer amount or destination. It must be a finite number, `>= 0` and below
+`1e12`; the SDK floors it to whole cents (`20.789` shows as `$20.78`). Anything
+else is dropped with a console error naming the field, and the deposit proceeds
+without the subtitle. When you don't pass it, Blink may fall back to showing
+the destination wallet's on-chain balance instead.
+
 ## Error Handling
 
 Every error is a `DepositError` with a machine-readable `code`:
@@ -145,6 +314,8 @@ transfer.on('complete', (result) => { /* DepositResult */ });
 transfer.on('error', (error) => { /* DepositError */ });
 transfer.on('close', () => { /* iframe closed */ });
 transfer.on('status-change', (status) => { /* DepositStatus */ });
+// Embedded presentation only — the inline iframe was resized to this height.
+transfer.on('resize', ({ heightPx }) => { /* number */ });
 ```
 
 ## Lifecycle