@nevermined-io/ui-widgets 0.3.1 → 0.4.1

package/README.md

@@ -0,0 +1,208 @@
+# @nevermined-io/ui-widgets
+
+Browser SDK for embedding Nevermined flows (checkout, card enrollment, card management, delegations) into your own website via secure iframes.
+
+Pairs with [`@nevermined-io/ui-widgets-server`](https://www.npmjs.com/package/@nevermined-io/ui-widgets-server), which mints the short-lived init tokens this SDK exchanges for an authenticated widget session.
+
+## Install
+
+```bash
+npm install @nevermined-io/ui-widgets
+# or
+pnpm add @nevermined-io/ui-widgets
+```
+
+ESM-only. Works in any modern browser bundler (Vite, webpack 5, Rspack, esbuild, etc.).
+
+## Quick start
+
+```ts
+import { NeverminedWidgets } from '@nevermined-io/ui-widgets'
+
+// 1. Get an init token from your backend (see ui-widgets-server)
+const { initToken } = await fetch('/api/widget-init-token').then(r => r.json())
+
+// 2. Initialize the SDK
+const nvm = await NeverminedWidgets.initialize({
+  initToken,
+  environment: 'sandbox',
+})
+
+// 3. Mount a widget
+nvm.checkout.start({
+  did: 'did:nv:abc...',
+  container: document.getElementById('checkout')!,
+  onReady: () => console.log('iframe ready'),
+  onSuccess: result => console.log('purchase complete', result),
+  onError: error => console.error('checkout error', error),
+  onClose: () => console.log('user closed the iframe'),
+})
+```
+
+The widget renders inside `container` as an iframe. The host page never sees Stripe details, the user's NVM API key, or the underlying blockchain transactions — those stay inside the iframe and the Nevermined backend.
+
+## Environments
+
+| Value             | API base URL                            | Webapp URL                  |
+| ----------------- | --------------------------------------- | --------------------------- |
+| `live`            | `https://api.live.nevermined.app`       | `https://nevermined.app`    |
+| `sandbox`         | `https://api.sandbox.nevermined.app`    | `https://nevermined.app`    |
+| `staging_live`    | `https://api.live.nevermined.dev`       | `https://nevermined.dev`    |
+| `staging_sandbox` | `https://api.sandbox.nevermined.dev`    | `https://nevermined.dev`    |
+| `local`           | `http://localhost:3001`                 | `http://localhost:4200`     |
+
+`local` is for developing against a self-hosted stack. Production integrations should use `live` or `sandbox`.
+
+## API
+
+### `NeverminedWidgets.initialize(config)`
+
+Exchanges the init token for a widget session. Returns a `NeverminedWidgets` instance you keep around for the lifetime of the page (or until logout).
+
+```ts
+const nvm = await NeverminedWidgets.initialize({
+  initToken: '...',     // from your backend
+  environment: 'live',
+})
+```
+
+The session refreshes itself automatically in the background. If a refresh fails (revoked widget key, expired session, network outage), the SDK emits `'session-expired'`:
+
+```ts
+nvm.on('session-expired', () => {
+  // Fetch a new init token from your backend and re-initialize.
+})
+```
+
+### `nvm.checkout.start(options)`
+
+Mounts the checkout iframe so the user can purchase a plan for a given agent DID.
+
+```ts
+nvm.checkout.start({
+  did: 'did:nv:...',
+  planId: '...',                 // optional: skip plan selection
+  container: HTMLElement,        // optional: defaults to document.body
+  onBooted: () => void,          // iframe DOM mounted, before auth
+  onReady: () => void,           // iframe authenticated and rendered
+  onSuccess: ({ did, planId, txHash }) => void,
+  onError: (error: EmbedError) => void,
+  onClose: () => void,           // iframe was dismissed; instance is now terminal
+})
+```
+
+After `onClose` the widget instance is terminal — call `nvm.checkout.start()` again on a fresh instance via `nvm.checkout` to mount another checkout.
+
+### `nvm.delegations`
+
+Card and delegation management. Three iframe-based flows + two SDK-direct revocations:
+
+```ts
+// Iframe flows
+nvm.delegations.enrollCard({ container, onSuccess, onError, onClose })
+nvm.delegations.listCards({ container, onCardAction, onError, onClose })
+nvm.delegations.createDelegation({ paymentMethodId, container, onSuccess, onError })
+
+// Direct API calls (no iframe) — use the widget session token under the hood
+await nvm.delegations.revokeCard(paymentMethodId)
+await nvm.delegations.revokeDelegation(delegationId)
+```
+
+`listCards` emits per-row actions through `onCardAction` so the host can react (e.g. mount `createDelegation` for the selected card):
+
+```ts
+nvm.delegations.listCards({
+  container,
+  onCardAction: ({ action, paymentMethodId }) => {
+    if (action === 'delegate') {
+      nvm.delegations.createDelegation({ paymentMethodId, container })
+    }
+  },
+})
+```
+
+The two iframe flows and `listCards` share a single iframe slot — calling any of them dismounts the previous iframe.
+
+### `nvm.account`
+
+```ts
+const { userId, userWallet } = nvm.account
+```
+
+The user identity backed by the widget session. `userWallet` is the user's smart account address.
+
+### `nvm.destroy()`
+
+Tears down any active iframe, stops the session refresh timer, and clears event listeners. Call this when the user logs out or you no longer need any widget on the page.
+
+## Errors
+
+### `WidgetInitError`
+
+Thrown by `NeverminedWidgets.initialize()` when the init token is rejected, the response is malformed, or the network call fails.
+
+```ts
+try {
+  await NeverminedWidgets.initialize({ initToken, environment: 'live' })
+} catch (err) {
+  if (err instanceof WidgetInitError) {
+    // err.code: MISSING_INIT_TOKEN | INVALID_INIT_TOKEN | INVALID_ENVIRONMENT
+    //         | INVALID_RESPONSE  | NETWORK_ERROR
+  }
+}
+```
+
+### `WidgetSessionExpiredError`
+
+Thrown by `nvm.getSessionToken()` when the cached session has expired and was not refreshed in time.
+
+### `WidgetApiError`
+
+Thrown by `revokeCard()` and `revokeDelegation()` on non-2xx responses or network failures. Carries `status` and the optional `apiCode` (BCK error code) so consumers can branch on `401`/`403` without parsing the message.
+
+### `EmbedError` (callback payload)
+
+Errors surfaced through `onError` callbacks have a normalized shape:
+
+```ts
+type EmbedError = {
+  code: 'UNAUTHORIZED' | 'NETWORK' | 'PAYMENT_NOT_CONFIRMED' | 'UNKNOWN'
+  message: string
+  status?: number    // HTTP status when applicable
+  apiCode?: string   // BCK.* error code when the iframe surfaces one
+}
+```
+
+## postMessage protocol
+
+The SDK and the embedded iframes communicate over `window.postMessage` with a versioned message envelope. Most consumers never need to deal with this directly, but the types are exported in case you want to inspect frames or build a custom integration:
+
+```ts
+import { WidgetMessageType, parseMessage, createMessage, WIDGET_MESSAGE_VERSION } from '@nevermined-io/ui-widgets'
+```
+
+Message types:
+
+| Type              | Direction          | When                                                      |
+| ----------------- | ------------------ | --------------------------------------------------------- |
+| `nvm:booted`      | iframe → parent    | DOM mounted, before the iframe knows the session token    |
+| `nvm:init`        | parent → iframe    | SDK responds to `booted` with the session token           |
+| `nvm:ready`       | iframe → parent    | Auth validated, iframe rendered                           |
+| `nvm:resize`      | iframe → parent    | Iframe content height changed                             |
+| `nvm:success`     | iframe → parent    | Terminal success (purchase complete, card enrolled, etc.) |
+| `nvm:error`       | iframe → parent    | Error (terminal or recoverable; check `EmbedError.code`)  |
+| `nvm:card-action` | iframe → parent    | Per-row action inside `listCards` (e.g. delegate)         |
+| `nvm:close`       | iframe ↔ parent    | Iframe is being dismissed                                 |
+
+All frames carry `version: '1'`. The SDK rejects frames with mismatched versions to keep upgrades safe.
+
+## Security model
+
+- **Origin allowlist:** every widget key has an `allowedOrigins` list. The webapp validates that the host's `parentOrigin` is on that list before responding to the handshake. A leaked widget key cannot mount widgets on an unrecognized origin.
+- **Session token never in URL:** the SDK delivers the session token to the iframe via `postMessage` after a `nvm:booted` handshake. The token is not visible in the iframe `src`, browser history, or referer headers.
+- **Wildcard origin rejected:** `IframeManager` refuses to construct with `'*'`.
+- **Sandboxed iframe:** the embed routes run in a no-chrome layout that excludes navigation, links to other dashboard areas, and persistent cookies for cross-origin contexts.
+
+## License
+
+Apache-2.0 © Nevermined

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nevermined-io/ui-widgets",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -17,5 +17,8 @@
     "dist",
     "!**/*.tsbuildinfo"
   ],
-  "devDependencies": {}
+  "devDependencies": {
+    "vite": "^8.0.5",
+    "vite-plugin-dts": "^4.5.4"
+  }
 }