@benji-money/connect-sdk 1.1.4-beta.1 → 1.1.4-beta.11

package/README.md

@@ -2,6 +2,8 @@
 
 A JavaScript Github Package SDK for integrating Benji Connect, Benji's authentication and verification services.
 
+LOGIN mode (surfaces, timers, host API): [docs/login-mode.md](./docs/login-mode.md).
+
 ## Installation
 
 ```bash
@@ -87,12 +89,22 @@ 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. Prefer `tokenData.authType` when using `tokenData`.
-- `tokenData` (optional): `BenjiConnectTokenData` — LOGIN only; pass `partnerAuthLink` (Auth Service `connect_url`) and `authType` so the SDK opens the partner auth URL synchronously in the popup on `open()` instead of `about:blank` + loading HTML
+- `authType` (optional): `PartnerIntegrationType` — LOGIN only; omit or set `DUMMY` for the visible modal iframe; set to your partner type (1–6) for the embedded sign-in button. Prefer `tokenData.authType` when using `tokenData`.
+- `login` (optional): `BenjiConnectLoginConfig` — LOGIN-only options:
+  - `container`: `HTMLElement | string` — **required** for the embedded LOGIN button. The element the visible Benji Connect iframe mounts into. The SDK never appends to `document.body` for this surface; a missing container reports through `onError`.
+  - `surface`: `BenjiConnectLoginSurface` — `EMBEDDED_BUTTON` (default for non-DUMMY LOGIN) or `MODAL` (default for DUMMY). Override only when a partner on a real integration type needs the modal.
+  - `windowTarget`: `BenjiConnectLoginWindowTarget` — LOGIN non-DUMMY only; `tab` (default) or `popup`. Forwarded to Benji Connect, which opens the window.
+  - `buttonText`: host-owned label. Omitted or empty → Connect paints `Login`.
+  - `buttonTheme`: resolved CSS values for the in-iframe button (fill, hover, type, radius).
+- `tokenData` (optional): `BenjiConnectTokenData` — LOGIN only; pass `partnerAuthLink` (Auth Service `connect_url`), `configToken` (mint `config_token`, used as OAuth `state`), and `authType`. Benji Connect resolves the auth link at iframe load, before any click.
 - `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
+- `onLoginDisplayed` (optional): Embedded LOGIN button only — Connect painted themed chrome (first visual handoff); prefer this for dropping the host skeleton/cover. Requires Benji Connect [BEN-2572] to emit `LOGIN_DISPLAYED`; do not rely on this callback until Connect is deployed.
+- `onLoginReady` (optional, deprecated for cover handoff): Embedded LOGIN button only — Connect resolved the auth link and rendered the button (session-ready). Prefer `onLoginDisplayed` for skeleton/cover removal.
+- `onLoginHover` (optional): Embedded LOGIN button only — pointer or focus entered the in-iframe button, for a host-owned tooltip
+- `onLoginClicked` (optional): Embedded LOGIN button only — the button was pressed, before the tab opens, for a host-owned pending state
 - `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 }`)
@@ -103,7 +115,7 @@ The SDK accepts the following configuration options:
 | ---- | ---------- | ----- |
 | **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` (or `tokenData.authType`); Benji Connect iframe is headless — popup opens partner auth immediately when `tokenData.partnerAuthLink` is set, otherwise shows loading UI until Benji Connect navigates — see [LOGIN popup example](#login-popup-example) below |
+| **LOGIN + non-DUMMY** | **Embedded sign-in button** plus a partner auth tab | Pass `authType` (or `tokenData.authType`) and `login.container`. Benji Connect renders the button inside a visible iframe and opens the partner tab itself, on every device. See [embedded LOGIN button example](#embedded-login-button-example) below. |
 
 ### Placement
 
@@ -118,7 +130,7 @@ Placement uses [Floating UI](https://floating-ui.com/docs/computePosition#placem
 **What `anchor` positions:**
 
 - **CONNECT, TRANSFER, REDEEM, and LOGIN + DUMMY:** the modal iframe
-- **LOGIN + non-DUMMY:** the partner-auth popup window (modal iframe stays headless)
+- **LOGIN + non-DUMMY:** nothing. The embedded button takes its box from `login.container`, so omit `anchor` / `placement` / `offset`.
 
 **Defaults:**
 
@@ -145,15 +157,18 @@ Prefer selector, ref, or getter when the anchor can re-render (e.g. disabled/loa
 - **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
+#### Embedded LOGIN button example
+
+Reserve a box in your own layout, hand it to the SDK, and let Benji Connect render the button inside it:
 
-Popup below a top-right login button; pass `authType` for non-DUMMY partners:
+```html
+<div id="benji-login" style="width: 140px; height: 40px"></div>
+```
 
 ```typescript
 import {
   ConnectSDK,
   BenjiConnectMode,
-  BenjiConnectPlacement,
   PartnerIntegrationType,
 } from "@benji-money/connect-sdk";
 
@@ -161,22 +176,29 @@ const sdk = new ConnectSDK({
   environment: "sandbox",
   token: connectToken,
   mode: BenjiConnectMode.LOGIN,
+  login: { container: "#benji-login" },
   tokenData: {
     authType: PartnerIntegrationType.OAUTH_PKCE,
     partnerAuthLink: connectUrl, // from Auth Service connect_url
+    configToken: configToken, // from GET /connect/token — OAuth state
   },
-  anchor: "#login-btn",
-  placement: BenjiConnectPlacement.BOTTOM_END,
-  offset: { top: 8 },
+  onLoginDisplayed: () => { /* hide your skeleton */ },
+  onLoginHover: () => { /* show your tooltip */ },
+  onLoginClicked: () => { /* show your pending state */ },
   onSuccess: (token) => { /* ... */ },
-  onError: (error) => { /* popup blocked, etc. */ },
-  onExit: (metadata) => { /* POPUP_CLOSED when user dismisses popup */ },
+  onError: (error) => { /* sign-in window blocked, etc. */ },
+  onExit: (metadata) => { /* toast: WINDOW_CLOSE_DETECTED; the button stays mounted */ },
 });
 
+// Mount on page load, not on click — the iframe resolves the partner auth link
+// while the user is still reading the page.
 await sdk.open();
+
+// Later, when your token refresh timer fires:
+sdk.updateConfig({ token: freshConnectToken, tokenData: { configToken: freshConfigToken } });
 ```
 
-> **`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). When `tokenData.partnerAuthLink` is set, the popup navigates to partner auth immediately on `open()`. Otherwise the pre-opened popup shows generic loading UI (`Loading sign-in…`) until Benji Connect sends the partner auth URL.
+> **Why the button lives in the iframe.** `window.open` needs transient user activation, and activation belongs to the document the click happened in. Because the click lands in Benji Connect's document, **Connect** opens the partner tab, so that tab's `opener` is the Connect iframe — same-origin with Connect's OAuth callback. That is what removes the host-side auth relay, the message queues, and the iOS-only same-tab redirect that earlier versions needed. Reserve the box in your own CSS: the SDK's iframe fills the container at 100% × 100% and contributes no geometry of its own.
 
 ### Environments