@juspay-tech/hyperswitch-control-center-embed-core 1.1.1 → 1.2.0

package/README.md

@@ -1,114 +1,166 @@
 # @juspay-tech/hyperswitch-control-center-embed-core
 
-Core JavaScript SDK for embedding Hyperswitch Control Center components into any web application.
+[![npm version](https://img.shields.io/npm/v/@juspay-tech/hyperswitch-control-center-embed-core.svg)](https://www.npmjs.com/package/@juspay-tech/hyperswitch-control-center-embed-core)
 
-## Overview
+The core JavaScript SDK for Hyperswitch Control Center embedded components. It lets you add Control Center functionality, such as connector configuration, payments and refunds, to your own website.
 
-The `loadHyperswitch` function is the main entry point for initializing embedded Hyperswitch components.  
-It:
-
-- **Loads UI via an iframe** from the Hyperswitch Control Center
-- **Requires a `fetchToken` function** that calls your backend to retrieve an embedded token
-- **Optionally accepts `initConfig`** to customize the appearance of the embedded UI
+This package contains the initialization logic for embedded components along with the related TypeScript types. It has no framework dependency. If you use React, see [`@juspay-tech/hyperswitch-control-center-embed-react`](https://www.npmjs.com/package/@juspay-tech/hyperswitch-control-center-embed-react).
 
 ## Installation
 
-```bash
+```sh
 npm install @juspay-tech/hyperswitch-control-center-embed-core
 ```
 
 or with `pnpm`:
 
-```bash
+```sh
 pnpm add @juspay-tech/hyperswitch-control-center-embed-core
 ```
 
-## Imports
+## Documentation
 
-### ES Module (recommended)
+- [Integration Guide](https://docs.hyperswitch.io/explore-hyperswitch/account-management/beta-embeddable-components/integration-guide)
+- [API reference](#api-reference)
 
-```javascript
-import { loadHyperswitch } from '@juspay-tech/hyperswitch-control-center-embed-core';
-```
+## Usage
 
-### CommonJS
+Embedded components authenticate with a short-lived embedded token. Your server requests the token from Hyperswitch with your API key, and the SDK retrieves it from your server through a `fetchToken` function that you provide. Your API key is never exposed to the browser.
 
-```javascript
-const { loadHyperswitch } = require('@juspay-tech/hyperswitch-control-center-embed-core');
-```
+### Issue an embedded token on your server
 
-## Basic usage
+Add an endpoint to your server that calls the Hyperswitch embedded token API and returns the token.
 
-Initialize the SDK by providing a `fetchToken` function that calls your backend:
+```js
+// GET /api/get-embedded-token
+app.get('/api/get-embedded-token', async (req, res) => {
+  const response = await fetch(`${process.env.HYPERSWITCH_API_URL}/embedded/token`, {
+    headers: {
+      'api-key': process.env.HYPERSWITCH_API_KEY,
+      'x-profile-id': process.env.HYPERSWITCH_PROFILE_ID,
+    },
+  });
 
-```javascript
-const hyperswitch = loadHyperswitch({
-  fetchToken: async () => {
-    // Call your backend endpoint to get the embedded token
-    const response = await fetch('https://your-api.com/embedded/hyperswitch', {
-      method: 'GET',
-      headers: { 'Content-Type': 'application/json' }
-    });
-    const data = await response.json();
-    return data.token;
+  if (!response.ok) {
+    return res.status(502).json({ error: 'Unable to issue an embedded token.' });
   }
+
+  const { token } = await response.json();
+  res.json({ token });
 });
 ```
 
-## Optional customization
+The token is scoped to the business profile passed in `x-profile-id`.
 
-You can customize the appearance by passing a theme configuration as `initConfig`:
+### `loadHyperswitch`
 
-```javascript
-const initConfig = {
-  primaryColor: '#0066ff',
-  backgroundColor: '#ffffff',
-  buttons: {
-    primary: {
-      backgroundColor: '#0066ff',
-      textColor: '#ffffff',
-      hoverBackgroundColor: '#0052cc'
-    },
-    secondary: {
-      backgroundColor: '#f0f0f0',
-      textColor: '#333333',
-      hoverBackgroundColor: '#e0e0e0'
-    }
-  }
+This synchronous function takes a function that retrieves the embedded token from your server, along with optional [appearance settings](#customizing-the-appearance). It returns a `Hyperswitch` instance.
+
+```js
+import { loadHyperswitch } from '@juspay-tech/hyperswitch-control-center-embed-core';
+
+const fetchToken = async () => {
+  // Fetch the embedded token by making an API call to your server
+  const response = await fetch('/api/get-embedded-token');
+  const { token } = await response.json();
+  return token;
 };
 
-const hyperswitch = loadHyperswitch({
-  fetchToken: async () => { /* ... */ },
-  initConfig
-});
+const hyperswitch = loadHyperswitch({ fetchToken });
 ```
 
-All fields in `initConfig` are optional. Omitting them uses the default Control Center theme.
+`fetchToken` is called when the instance is created, and again whenever the token expires.
 
-## Creating a component
+The package also supports CommonJS:
 
-Create an embeddable component instance:
+```js
+const { loadHyperswitch } = require('@juspay-tech/hyperswitch-control-center-embed-core');
+```
 
-```javascript
-const connectors = hyperswitch.create('connectors', {
-  url: 'https://app.hyperswitch.io'
+### Creating and mounting a component
+
+Create a component from the instance and mount it to an element on your page.
+
+```html
+<div id="hyperswitch-root"></div>
+```
+
+```js
+const payments = hyperswitch.create('payments', {
+  url: 'https://app.hyperswitch.io',
 });
+
+payments.mount('#hyperswitch-root');
 ```
 
-Currently available component: `connectors`.
+To remove a component, call `payments.destroy()`.
 
-## Mounting
+### Supported components
 
-Mount the component into a container element in your HTML:
+| Name | Description |
+|------|-------------|
+| `connectors` | Connector configuration |
+| `payments` | Payments list and payment details |
+| `refunds` | Refunds list and refund details |
 
-```html
-<div id="hyperswitch-root"></div>
+Multiple components can be created from a single instance.
+
+### Environments
+
+The `url` option is the base URL of the Control Center that serves the components. The embedded token must be issued by the same environment.
+
+| Environment | `url` | Token API base URL |
+|-------------|-------|--------------------|
+| Sandbox | `https://app.hyperswitch.io` | `https://app.hyperswitch.io/api` |
+| Production | `https://live.hyperswitch.io` | `https://live.hyperswitch.io/api` |
+
+### Customizing the appearance
+
+Pass a theme configuration as `initConfig` to match the components to your brand.
+
+```js
+const hyperswitch = loadHyperswitch({
+  fetchToken,
+  initConfig: {
+    primaryColor: '#0066ff',
+    backgroundColor: '#ffffff',
+    buttons: {
+      primary: {
+        backgroundColor: '#0066ff',
+        textColor: '#ffffff',
+        hoverBackgroundColor: '#0052cc',
+      },
+      secondary: {
+        backgroundColor: '#f0f0f0',
+        textColor: '#333333',
+        hoverBackgroundColor: '#e0e0e0',
+      },
+    },
+  },
+});
 ```
 
-```javascript
-connectors.mount('#hyperswitch-root');
+All fields in `initConfig` are optional. Omitted fields use the default Control Center theme. See [`MerchantTheme`](#merchanttheme) for the complete list.
+
+### Modals
+
+Modals opened inside a component are displayed over the full host page. While a modal is open, the SDK stretches the component's iframe across the window and locks page scrolling, and restores both when the modal closes.
+
+To keep modals inside the component, set `fullPageModals` to `false`:
+
+```js
+const payments = hyperswitch.create('payments', {
+  url: 'https://app.hyperswitch.io',
+  fullPageModals: false,
+});
 ```
 
+Full-page modals rely on `position: fixed`. If an ancestor of the mount point has a CSS `transform`, `filter`, `perspective` or `contain`, or creates a stacking context below other page content, the modal can be clipped or covered. Set `fullPageModals` to `false` in that layout.
+
+### Content Security Policy
+
+If you have deployed a [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP), include the Control Center origin in your `frame-src` directive.
+
 ## API reference
 
 ### `loadHyperswitch(options)`
@@ -117,8 +169,8 @@ Returns a `Hyperswitch` instance.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `fetchToken` | `() => Promise<string \| undefined>` | Yes | Async function that fetches the embedded token from your backend |
-| `initConfig` | `MerchantTheme` | No | Theme customization object |
+| `fetchToken` | `() => Promise<string \| undefined>` | Yes | Async function that fetches the embedded token from your server |
+| `initConfig` | [`MerchantTheme`](#merchanttheme) | No | Theme customization object |
 
 ### `MerchantTheme`
 
@@ -135,23 +187,47 @@ Returns a `Hyperswitch` instance.
 | `buttons?.secondary?.textColor?` | `string` | Secondary button text color |
 | `buttons?.secondary?.hoverBackgroundColor?` | `string` | Secondary button hover color |
 
-### `Hyperswitch.create(name, options)`
+### `hyperswitch.create(name, options)`
 
 Creates a component instance.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `name` | `string` | Component name (e.g., `'connectors'`) |
-| `options.url` | `string` | Base URL for the embedded component |
+| `name` | `'connectors' \| 'payments' \| 'refunds'` | The component to create |
+| `options` | [`ElementOptions`](#elementoptions) | Component options |
 
-### `.mount(selector)`
+### `ElementOptions`
 
-Mounts the component to a DOM element matching the given CSS selector.
+| Property | Type | Description |
+|----------|------|-------------|
+| `url` | `string` | Base URL of the Control Center that serves the component |
+| `width?` | `string` | Width of the component container. Defaults to `100%` |
+| `height?` | `string` | Initial height of the component container. The component resizes to fit its content |
+| `className?` | `string` | Additional class names for the component container |
+| `style?` | `Partial<CSSStyleDeclaration>` | Inline styles for the component container |
+| `fullPageModals?` | `boolean` | Display modals over the full host page. Defaults to `true` |
+| `onResize?` | `(dimensions: { width: number; height: number }) => void` | Called when the component is resized |
 
-## Documentation
+### `component.mount(target)`
 
-For more details and examples, see the [Integration Guide](https://docs.hyperswitch.io/explore-hyperswitch/account-management/beta-embeddable-components/integration-guide).
+Mounts the component to a DOM element. `target` is a CSS selector or an `HTMLElement`. Returns the component.
+
+### `component.destroy()`
+
+Removes the component from the page and cleans up its event listeners.
+
+## TypeScript support
+
+This package includes TypeScript declarations. The following types are exported:
+
+```ts
+import type {
+  HyperswitchInitOptions,
+  ElementOptions,
+  MerchantTheme,
+} from '@juspay-tech/hyperswitch-control-center-embed-core';
+```
 
 ## License
 
-MIT
+MIT

package/dist/element.d.ts

@@ -7,14 +7,23 @@ declare abstract class HyperswitchElement {
     protected iframe: HTMLIFrameElement;
     private boundMessageHandler;
     readonly _internalId: string;
+    private isFullPage;
+    private previousBodyOverflow;
+    private showIframeTimer;
+    private iframeOrigin;
     constructor(instance: Hyperswitch, options?: ElementOptions);
     private setupElement;
     private setupIframe;
     private handleMessage;
+    private setFullPage;
+    private showIframe;
     mount(domNode: string | HTMLElement): HyperswitchElement;
     destroy(): void;
     protected abstract getElementType(): string;
     protected abstract getIframeSrc(): string;
     getIframe(): HTMLIFrameElement;
+    acceptMessage(event: MessageEvent): boolean;
+    postMessageToIframe(message: Record<string, unknown>): void;
+    isFullPageModalEnabled(): boolean;
 }
 export { HyperswitchElement };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { loadHyperswitch, Hyperswitch } from './hyperswitch';
 export { HyperswitchElement } from './element';
 export { ConnectorConfigurationComponent } from './connector-configuration';
+export { PaymentsComponent } from './payments';
+export { RefundsComponent } from './refunds';
 export type { HyperswitchInitOptions, ElementOptions } from './types';
 export type { MerchantTheme } from './init-config';
 export declare const VERSION = "1.0.0";

package/dist/index.esm.js

@@ -1,6 +1,10 @@
 const isBrowser$1 = typeof window !== 'undefined';
 class HyperswitchElement {
     constructor(instance, options) {
+        this.isFullPage = false;
+        this.previousBodyOverflow = '';
+        this.showIframeTimer = null;
+        this.iframeOrigin = null;
         this.instance = instance;
         this.options = options || {};
         this._internalId = `hyper-el-${Math.random().toString(36).substring(7)}`;
@@ -40,17 +44,31 @@ class HyperswitchElement {
         this.element.appendChild(this.iframe);
     }
     handleMessage(event) {
-        var _a;
+        var _a, _b, _c, _d;
         if (!isBrowser$1) {
             return;
         }
         if (this.options.onMessage) {
             this.options.onMessage(event.data);
         }
-        if (((_a = event.data) === null || _a === void 0 ? void 0 : _a.type) === 'EMBEDDED_COMPONENT_RESIZE') {
+        if (!this.acceptMessage(event)) {
+            return;
+        }
+        if (this.isFullPageModalEnabled()) {
+            if (((_a = event.data) === null || _a === void 0 ? void 0 : _a.type) === 'EMBEDDED_MODAL_OPEN') {
+                this.setFullPage(true);
+            }
+            else if (((_b = event.data) === null || _b === void 0 ? void 0 : _b.type) === 'EMBEDDED_MODAL_CLOSE') {
+                this.setFullPage(false);
+            }
+            else if (((_c = event.data) === null || _c === void 0 ? void 0 : _c.type) === 'EMBEDDED_MODAL_VISIBLE') {
+                this.showIframe();
+            }
+        }
+        if (((_d = event.data) === null || _d === void 0 ? void 0 : _d.type) === 'EMBEDDED_COMPONENT_RESIZE') {
             const newHeight = event.data.height;
             const messageComponent = event.data.component || '';
-            if (messageComponent === this.getElementType() && typeof newHeight === 'number' && newHeight > 0) {
+            if (!this.isFullPage && messageComponent === this.getElementType() && typeof newHeight === 'number' && newHeight > 0) {
                 this.element.style.height = `${newHeight}px`;
                 if (this.options.onResize) {
                     this.options.onResize({
@@ -61,6 +79,49 @@ class HyperswitchElement {
             }
         }
     }
+    setFullPage(isFullPage) {
+        if (isFullPage !== this.isFullPage) {
+            this.isFullPage = isFullPage;
+            this.iframe.style.visibility = 'hidden';
+            if (isFullPage) {
+                this.previousBodyOverflow = document.body.style.overflow;
+                document.body.style.overflow = 'hidden';
+                Object.assign(this.iframe.style, {
+                    position: 'fixed',
+                    top: '0',
+                    left: '0',
+                    width: '100vw',
+                    height: '100vh',
+                    zIndex: '2147483647'
+                });
+            }
+            else {
+                document.body.style.overflow = this.previousBodyOverflow;
+                Object.assign(this.iframe.style, {
+                    position: '',
+                    top: '',
+                    left: '',
+                    width: '100%',
+                    height: '100%',
+                    zIndex: ''
+                });
+            }
+            if (this.showIframeTimer) {
+                clearTimeout(this.showIframeTimer);
+            }
+            this.showIframeTimer = setTimeout(() => this.showIframe(), 300);
+        }
+        this.postMessageToIframe({
+            type: isFullPage ? 'EMBEDDED_MODAL_OPENED' : 'EMBEDDED_MODAL_CLOSED'
+        });
+    }
+    showIframe() {
+        if (this.showIframeTimer) {
+            clearTimeout(this.showIframeTimer);
+            this.showIframeTimer = null;
+        }
+        this.iframe.style.visibility = '';
+    }
     mount(domNode) {
         if (!isBrowser$1) {
             throw new Error('HyperswitchElement.mount can only be called in a browser environment');
@@ -78,6 +139,14 @@ class HyperswitchElement {
         if (!isBrowser$1) {
             return;
         }
+        if (this.isFullPage) {
+            this.isFullPage = false;
+            document.body.style.overflow = this.previousBodyOverflow;
+        }
+        if (this.showIframeTimer) {
+            clearTimeout(this.showIframeTimer);
+            this.showIframeTimer = null;
+        }
         if (this.boundMessageHandler) {
             window.removeEventListener('message', this.boundMessageHandler);
         }
@@ -88,6 +157,26 @@ class HyperswitchElement {
     getIframe() {
         return this.iframe;
     }
+    acceptMessage(event) {
+        var _a;
+        if (event.source !== ((_a = this.iframe) === null || _a === void 0 ? void 0 : _a.contentWindow)) {
+            return false;
+        }
+        if (this.iframeOrigin === null && event.origin && event.origin !== 'null') {
+            this.iframeOrigin = event.origin;
+        }
+        return this.iframeOrigin === null || event.origin === this.iframeOrigin;
+    }
+    postMessageToIframe(message) {
+        var _a, _b;
+        if (this.iframeOrigin === null) {
+            return;
+        }
+        (_b = (_a = this.iframe) === null || _a === void 0 ? void 0 : _a.contentWindow) === null || _b === void 0 ? void 0 : _b.postMessage(message, this.iframeOrigin);
+    }
+    isFullPageModalEnabled() {
+        return this.options.fullPageModals !== false;
+    }
 }
 
 class ConnectorConfigurationComponent extends HyperswitchElement {
@@ -103,6 +192,32 @@ class ConnectorConfigurationComponent extends HyperswitchElement {
     }
 }
 
+class PaymentsComponent extends HyperswitchElement {
+    constructor(instance, options) {
+        super(instance, options);
+    }
+    getElementType() {
+        return 'payments';
+    }
+    getIframeSrc() {
+        const baseUrl = this.options.url || 'http://localhost:9000';
+        return `${baseUrl}/embedded/payments`;
+    }
+}
+
+class RefundsComponent extends HyperswitchElement {
+    constructor(instance, options) {
+        super(instance, options);
+    }
+    getElementType() {
+        return 'refunds';
+    }
+    getIframeSrc() {
+        const baseUrl = this.options.url || 'http://localhost:9000';
+        return `${baseUrl}/embedded/refunds`;
+    }
+}
+
 /**
  * Build the init_config object that Control Center expects
  * from the simple MerchantTheme contract.
@@ -188,17 +303,15 @@ class Hyperswitch {
         }
         window.addEventListener("message", async (event) => {
             var _a, _b, _c;
+            const sourceElement = Array.from(this.activeElements.values()).find((element) => element.acceptMessage(event));
+            if (!sourceElement) {
+                return;
+            }
             if (((_a = event.data) === null || _a === void 0 ? void 0 : _a.type) === "TOKEN_EXPIRED" && ((_b = event.data) === null || _b === void 0 ? void 0 : _b.value) === true) {
                 await this.refetchAndBroadcastToken();
             }
             else if (((_c = event.data) === null || _c === void 0 ? void 0 : _c.type) === "EMBEDDED_IFRAME_READY") {
-                // Find the element whose iframe matches the event source
-                this.activeElements.forEach((element) => {
-                    const iframe = element.getIframe();
-                    if ((iframe === null || iframe === void 0 ? void 0 : iframe.contentWindow) === event.source) {
-                        this.onElementIframeLoaded(element);
-                    }
-                });
+                this.onElementIframeLoaded(sourceElement);
             }
         });
     }
@@ -212,14 +325,11 @@ class Hyperswitch {
             if (newToken) {
                 this.token = newToken;
                 this.tokenError = null;
-                this.activeElements.forEach((element, elementId) => {
-                    const iframe = element.getIframe();
-                    if (iframe === null || iframe === void 0 ? void 0 : iframe.contentWindow) {
-                        iframe.contentWindow.postMessage({
-                            type: 'AUTH_TOKEN',
-                            token: this.token
-                        }, '*');
-                    }
+                this.activeElements.forEach((element) => {
+                    element.postMessageToIframe({
+                        type: 'AUTH_TOKEN',
+                        token: this.token
+                    });
                 });
             }
             else {
@@ -237,13 +347,10 @@ class Hyperswitch {
     }
     sendErrorToActiveElements(errorMessage) {
         this.activeElements.forEach((element) => {
-            const iframe = element.getIframe();
-            if (iframe === null || iframe === void 0 ? void 0 : iframe.contentWindow) {
-                iframe.contentWindow.postMessage({
-                    type: 'AUTH_ERROR',
-                    error: errorMessage
-                }, '*');
-            }
+            element.postMessageToIframe({
+                type: 'AUTH_ERROR',
+                error: errorMessage
+            });
         });
     }
     create(type, options) {
@@ -252,6 +359,12 @@ class Hyperswitch {
             case 'connectors':
                 element = new ConnectorConfigurationComponent(this, options);
                 break;
+            case 'payments':
+                element = new PaymentsComponent(this, options);
+                break;
+            case 'refunds':
+                element = new RefundsComponent(this, options);
+                break;
             default:
                 throw new Error(`Unknown element type: ${type}`);
         }
@@ -265,55 +378,47 @@ class Hyperswitch {
                 return;
             }
             setTimeout(() => {
+                var _a;
                 try {
-                    const contentWindow = iframe.contentWindow;
-                    if (!contentWindow) {
-                        return;
-                    }
                     if (this.tokenError) {
-                        contentWindow.postMessage({
+                        element.postMessageToIframe({
                             type: 'AUTH_ERROR',
                             error: this.tokenError
-                        }, '*');
+                        });
                     }
                     else if (this.token) {
-                        contentWindow.postMessage({
+                        element.postMessageToIframe({
                             type: 'AUTH_TOKEN',
                             token: this.token
-                        }, '*');
+                        });
                     }
                     else {
-                        contentWindow.postMessage({
+                        element.postMessageToIframe({
                             type: 'AUTH_ERROR',
                             error: 'No token available'
-                        }, '*');
-                    }
-                    // Send init_config (if available) as a separate message
-                    if (this.initConfig) {
-                        contentWindow.postMessage({
-                            type: 'INIT_CONFIG',
-                            init_config: this.initConfig
-                        }, '*');
+                        });
                     }
+                    // Always send init_config. If merchant doesn't provide it, send an empty object.
+                    element.postMessageToIframe({
+                        type: 'INIT_CONFIG',
+                        init_config: (_a = this.initConfig) !== null && _a !== void 0 ? _a : {},
+                        sdk_capabilities: { full_page_modal: element.isFullPageModalEnabled() }
+                    });
                 }
                 catch (error) {
                 }
             }, 100);
         }).catch((error) => {
-            const iframe = element.getIframe();
-            const contentWindow = iframe === null || iframe === void 0 ? void 0 : iframe.contentWindow;
-            if (contentWindow) {
-                setTimeout(() => {
-                    try {
-                        contentWindow.postMessage({
-                            type: 'AUTH_ERROR',
-                            error: `Token initialization failed: ${error instanceof Error ? error.message : String(error)}`
-                        }, '*');
-                    }
-                    catch (_a) {
-                    }
-                }, 100);
-            }
+            setTimeout(() => {
+                try {
+                    element.postMessageToIframe({
+                        type: 'AUTH_ERROR',
+                        error: `Token initialization failed: ${error instanceof Error ? error.message : String(error)}`
+                    });
+                }
+                catch (_a) {
+                }
+            }, 100);
         });
     }
 }
@@ -323,5 +428,5 @@ function loadHyperswitch(options) {
 
 const VERSION = '1.0.0';
 
-export { ConnectorConfigurationComponent, Hyperswitch, HyperswitchElement, VERSION, loadHyperswitch };
+export { ConnectorConfigurationComponent, Hyperswitch, HyperswitchElement, PaymentsComponent, RefundsComponent, VERSION, loadHyperswitch };
 //# sourceMappingURL=index.esm.js.map