@benji-money/connect-sdk 1.1.0-beta.1 → 1.1.0-beta.3

package/README.md

@@ -86,10 +86,93 @@ The SDK accepts the following configuration options:
 
 - `environment` (required): One of `local`, `development`, `sandbox`, or `production`
 - `token` (required): Your API connect token
+- `mode` (optional): `BenjiConnectMode` — `CONNECT` (default), `TRANSFER`, `REDEEM`, or `LOGIN`
+- `authType` (optional): `PartnerIntegrationType` — LOGIN only; omit or set `DUMMY` for the visible modal iframe; set to your partner type (1–6) for popup-only auth
 - `onSuccess` (optional): Callback function called when connect completed successfully
 - `onError` (optional): Callback function called when error occurs in the connect flow
 - `onExit` (optional): Callback function called when the user exits the connect flow
 - `onEvent` (optional): Callback function for handling various events
+- `anchor` (optional): Live anchor binding — `HTMLElement`, CSS selector, getter `() => HTMLElement | null`, or ref `{ value: HTMLElement | null }`. Re-resolved on every layout pass. Falls back to centered when missing or invalid. See [Placement](#placement)
+- `placement` (optional): Placement relative to `anchor` — see [Placement](#placement) below
+- `offset` (optional): Pixel gap after placement — `{ top?: number; left?: number }` (default `{ top: 0, left: 0 }`)
+
+### Modes
+
+| Mode | Visible UX | Notes |
+| ---- | ---------- | ----- |
+| **CONNECT** (default) | Centered or anchored modal iframe | No `authType`; standard connect / verify flow |
+| **LOGIN + DUMMY / no `authType`** | Same visible modal iframe | Partner auth runs in a nested iframe inside Benji Connect |
+| **LOGIN + non-DUMMY** | Partner popup only | Pass `authType`; Benji Connect iframe is headless — see [LOGIN popup example](#login-popup-example) below |
+
+### Placement
+
+Placement uses [Floating UI](https://floating-ui.com/docs/computePosition#placement) / CSS logical naming (`start` / `end`). In **LTR** layouts:
+
+| Value | Meaning |
+| ----- | ------- |
+| `center` (default) | Full-viewport backdrop with iframe centered |
+| `bottom-end` | Below the anchor, right edge aligned with anchor's right edge |
+| `bottom-start` | Below the anchor, left edge aligned with anchor's left edge |
+
+**What `anchor` positions:**
+
+- **CONNECT, TRANSFER, REDEEM, and LOGIN + DUMMY:** the modal iframe
+- **LOGIN + non-DUMMY:** the partner-auth popup window (modal iframe stays headless)
+
+**Defaults:**
+
+- No `anchor` → centered modal (unchanged behavior for existing integrations)
+- `anchor` set, no `placement` → `bottom-end`
+- If the anchor is missing or invalid on **initial open**, there is not enough viewport space below, or the viewport is narrower than the iframe (400px + padding), the SDK falls back to centered
+- While the modal is **already open**, a temporarily hidden or detached anchor (e.g. crossing a responsive layout breakpoint) keeps the last anchored position instead of jumping to center; when the anchor becomes visible again, placement re-anchors automatically
+
+**Live anchor bindings** (re-resolved on scroll, resize, and visual viewport changes):
+
+| Form | Example | When to use |
+| ---- | ------- | ----------- |
+| CSS selector | `'#login-btn'` | Stable id on the anchor element |
+| Ref object | `loginButtonRef` (Vue `{ value: el }`) | Anchor may re-render after async work |
+| Getter | `() => document.querySelector('#login-btn')` | Custom lookup |
+| `HTMLElement` | Snapshot at click time | Only when the node will not be replaced before `open()` |
+
+Prefer selector, ref, or getter when the anchor can re-render (e.g. disabled/loading state) before the modal opens. A stale `HTMLElement` snapshot falls back to a centered modal on open instead of clipping to the top-left; while open, resize across breakpoints preserves the last anchored position until the anchor is visible again or the modal is closed.
+
+**Viewport sizing:**
+
+- Design size is **400×645** px (`IFRAME_WIDTH` / `IFRAME_HEIGHT`)
+- **Centered** modals (default, explicit, or fallback) scale down proportionally when the viewport is smaller than the design size so the modal fits with 8px padding on each side
+- **Anchored** popovers use the full design size when width and height checks pass; otherwise they fall back to a scaled centered modal
+- Scroll, resize, and visual viewport changes while open recompute placement and size
+
+#### LOGIN popup example
+
+Popup below a top-right login button; pass `authType` for non-DUMMY partners:
+
+```typescript
+import {
+  ConnectSDK,
+  BenjiConnectMode,
+  BenjiConnectPlacement,
+  PartnerIntegrationType,
+} from "@benji-money/connect-sdk";
+
+const sdk = new ConnectSDK({
+  environment: "sandbox",
+  token: connectToken,
+  mode: BenjiConnectMode.LOGIN,
+  authType: PartnerIntegrationType.OAUTH_PKCE,
+  anchor: "#login-btn",
+  placement: BenjiConnectPlacement.BOTTOM_END,
+  offset: { top: 8 },
+  onSuccess: (token) => { /* ... */ },
+  onError: (error) => { /* popup blocked, etc. */ },
+  onExit: (metadata) => { /* POPUP_CLOSED when user dismisses popup */ },
+});
+
+await sdk.open();
+```
+
+> **`bottom-end`** positions the **partner popup** below the anchor with its right edge aligned to the anchor's right edge. The Benji Connect iframe stays headless (not visible).
 
 ### Environments