@morefin/cashier-bootstrapper 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# Cashier Bootstrapper
+
+Lightweight iframe bootstrapper for the Morefin cashier. It builds the cashier URL from request params and mounts the cashier inside an iframe to keep host styles isolated.
+
+## Installation
+
+```bash
+npm install @morefin/cashier-bootstrapper
+```
+
+## Usage
+
+Throughout the examples below, set a host variable once and reuse it:
+
+```typescript
+const CASHIER_HOST = 'http://localhost:7082'; // change per environment
+```
+
+### Basic Embed
+
+```typescript
+import { CashierBootstrapper } from '@morefin/cashier-bootstrapper';
+
+new CashierBootstrapper('#cashier-root', {
+  properties: { host: CASHIER_HOST }
+});
+```
+
+### Custom Request Params and Iframe Options
+
+```typescript
+import { CashierBootstrapper } from '@morefin/cashier-bootstrapper';
+
+new CashierBootstrapper('#cashier-root', {
+  requestParams: {
+    merchantId: 'merchant-123',
+    terminalId: 'terminal-456',
+    userId: 'user-789',
+    sessionId: 'session-abc',
+    predefinedAmounts: [100, 200, 300],
+    layout: 'default'
+  },
+  properties: {
+    host: CASHIER_HOST,
+    cashierPath: '/cashier',
+    iframe: {
+      height: '720px',
+      minHeight: '640px',
+      title: 'Morefin Cashier'
+    }
+  }
+}, api => {
+  console.log('Cashier iframe ready', api.iframe);
+});
+```
+
+### Provide Container via Config
+
+```typescript
+import { CashierBootstrapper } from '@morefin/cashier-bootstrapper';
+
+new CashierBootstrapper(null, {
+  properties: {
+    host: CASHIER_HOST,
+    container: '#cashier-root'
+  }
+});
+```
+
+### Runtime Controls (CSS + Data)
+
+```typescript
+import { CashierBootstrapper } from '@morefin/cashier-bootstrapper';
+
+new CashierBootstrapper('#cashier-root', {
+  properties: { host: CASHIER_HOST }
+}, api => {
+  api.setCss(`
+    .payment-layout-root .payment-container {
+      border: 2px dashed hotpink;
+    }
+  `);
+
+  api.updateData({ userId: 'updated-user' });
+});
+```
+
+## Examples Folder
+
+- `examples/npm` contains a minimal app that installs the package from npm and bundles it with esbuild.
+- `src/example-usage.ts` contains additional snippets for reference.
+
+## API
+
+### `new CashierBootstrapper(container, config?, onReady?)`
+
+Iframe-based embed that loads the cashier URL and exposes runtime controls once ready.
+
+**Parameters:**
+- `container: string | HTMLElement | null | undefined` - Where the iframe is appended. If omitted, `config.properties.container` is used (falling back to `document.body`).
+- `config?: CashierIframeConfig` - Request params and iframe properties. `properties.host` is required.
+- `onReady?: (api: CashierIframeApi) => void` - Called when the iframe loads; exposes helpers:
+  - `api.setCss(css: string)` – inject CSS inside the cashier iframe
+  - `api.updateData(data: object)` – post updated `APP_DATA` to the cashier
+  - `api.pause()` / `api.resume()` – forward pause/resume signals
+
+## Types
+
+```typescript
+interface CashierRequestParams {
+  merchantId?: string;
+  terminalId?: string;
+  userId?: string;
+  sessionId?: string;
+  predefinedAmounts?: number[];
+  layout?: string;
+  fingerprint?: string;
+}
+
+interface CashierIframeOptions {
+  width?: string;
+  height?: string;
+  minHeight?: string;
+  title?: string;
+  allow?: string;
+  sandbox?: string;
+  attributes?: Record<string, string>;
+}
+
+interface CashierIframeProperties {
+  host: string;
+  container?: string | HTMLElement;
+  cashierPath?: string;
+  iframe?: CashierIframeOptions;
+}
+
+interface CashierIframeConfig {
+  requestParams?: CashierRequestParams;
+  properties?: CashierIframeProperties;
+}
+```
+
+## Defaults
+
+- `cashierPath`: `/cashier`
+- `iframe.width`/`iframe.height`: `100%`
+- `iframe.allow`: `geolocation *;camera *;payment *;clipboard-read *;clipboard-write *;autoplay *;microphone *;fullscreen *;accelerometer *;magnetometer *;gyroscope *;picture-in-picture *;otp-credentials *;`

package/dist/example-usage.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Example usage file - demonstrates how to use the cashier bootstrapper.
+ * This file is not included in the npm package, it's just for reference.
+ */
+export declare function example1(): void;
+export declare function example2(container: string | HTMLElement): void;
+export declare function example3(): void;
+export declare function example4(container: string | HTMLElement): void;
+export declare function example5(container: string | HTMLElement): void;

package/dist/example-usage.js

@@ -0,0 +1,73 @@
+/**
+ * Example usage file - demonstrates how to use the cashier bootstrapper.
+ * This file is not included in the npm package, it's just for reference.
+ */
+import { CashierBootstrapper } from './index';
+const CASHIER_HOST = 'http://localhost:7082'; // change per environment
+// Example 1: Minimal configuration with selector
+export function example1() {
+    new CashierBootstrapper('#cashier-root', {
+        properties: { host: CASHIER_HOST }
+    });
+}
+// Example 2: Custom request params + iframe options
+export function example2(container) {
+    new CashierBootstrapper(container, {
+        requestParams: {
+            merchantId: 'merchant-123',
+            terminalId: 'terminal-456',
+            userId: 'user-789',
+            sessionId: 'session-abc',
+            predefinedAmounts: [100, 200, 300],
+            layout: 'default'
+        },
+        properties: {
+            host: CASHIER_HOST,
+            cashierPath: '/cashier',
+            iframe: {
+                height: '720px',
+                minHeight: '640px',
+                title: 'Morefin Cashier'
+            }
+        }
+    }, api => {
+        console.log('Cashier iframe ready', api.iframe);
+    });
+}
+// Example 3: Provide container via config instead of constructor
+export function example3() {
+    new CashierBootstrapper(null, {
+        properties: { host: CASHIER_HOST, container: '#cashier-root' }
+    });
+}
+// Example 4: Update CSS at runtime after iframe is ready
+export function example4(container) {
+    new CashierBootstrapper(container, {
+        requestParams: {
+            merchantId: 'merchant-123',
+            terminalId: 'terminal-456',
+            userId: 'user-789',
+            predefinedAmounts: [100, 200, 300],
+            layout: 'default'
+        },
+        properties: {
+            host: CASHIER_HOST
+        }
+    }, api => {
+        api.setCss(`
+      .payment-layout-root .payment-container {
+        border: 2px dashed hotpink;
+      }
+    `);
+    });
+}
+// Example 5: Updating data via the postMessage API
+export function example5(container) {
+    new CashierBootstrapper(container, {
+        properties: { host: CASHIER_HOST }
+    }, api => {
+        api.updateData({
+            userId: 'updated-user'
+        });
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { CashierIframeApi, CashierIframeConfig } from './types';
+export type { CashierRequestParams, CashierIframeApi, CashierIframeConfig, CashierIframeProperties } from './types';
+type FingerprintJSGlobal = {
+    load: () => Promise<{
+        get: () => Promise<{
+            visitorId: string;
+        }>;
+    }>;
+};
+declare global {
+    interface Window {
+        FingerprintJS?: FingerprintJSGlobal;
+    }
+}
+export declare class CashierBootstrapper {
+    private iframe?;
+    private origin;
+    private ready;
+    private readonly fullConfig;
+    private readonly onReady?;
+    constructor(container: string | HTMLElement | null | undefined, config?: CashierIframeConfig, onReady?: (api: CashierIframeApi) => void);
+    private bootstrapIframe;
+    private createIframeShell;
+    private handleLoad;
+    private postMessage;
+    /**
+     * API exposed to host pages for runtime control.
+     */
+    api(): CashierIframeApi;
+}

package/dist/index.js

@@ -0,0 +1,194 @@
+const DEFAULT_IFRAME_ALLOW = 'geolocation *;camera *;payment *;clipboard-read *;clipboard-write *;autoplay *;microphone *;fullscreen *;accelerometer *;magnetometer *;gyroscope *;picture-in-picture *;otp-credentials *;';
+const FINGERPRINT_CDN = 'https://cdn.jsdelivr.net/npm/@fingerprintjs/fingerprintjs@4/dist/fp.min.js';
+let fpLoaderPromise;
+function loadFingerprintLibrary() {
+    if (typeof window === 'undefined') {
+        return Promise.reject(new Error('FingerprintJS requires a browser environment'));
+    }
+    if (window.FingerprintJS) {
+        return Promise.resolve(window.FingerprintJS);
+    }
+    if (fpLoaderPromise) {
+        return fpLoaderPromise;
+    }
+    fpLoaderPromise = new Promise((resolve, reject) => {
+        const script = document.createElement('script');
+        script.src = FINGERPRINT_CDN;
+        script.async = true;
+        script.onload = () => {
+            if (window.FingerprintJS) {
+                resolve(window.FingerprintJS);
+            }
+            else {
+                reject(new Error('FingerprintJS did not register on window'));
+            }
+        };
+        script.onerror = () => reject(new Error('Failed to load FingerprintJS from CDN'));
+        document.head.appendChild(script);
+    });
+    return fpLoaderPromise;
+}
+async function generateFingerprint() {
+    try {
+        const fpLib = await loadFingerprintLibrary();
+        const fp = await fpLib.load();
+        const result = await fp.get();
+        return result.visitorId;
+    }
+    catch (err) {
+        console.warn('Fingerprint generation failed; continuing without it', err);
+        return undefined;
+    }
+}
+function buildQueryString(requestParams) {
+    const query = new URLSearchParams();
+    if (requestParams.merchantId != null) {
+        query.append('merchantId', String(requestParams.merchantId));
+    }
+    if (requestParams.terminalId != null) {
+        query.append('terminalId', String(requestParams.terminalId));
+    }
+    if (requestParams.userId != null) {
+        query.append('userId', String(requestParams.userId));
+    }
+    if (requestParams.sessionId != null) {
+        query.append('sessionId', String(requestParams.sessionId));
+    }
+    if (Array.isArray(requestParams.predefinedAmounts)) {
+        requestParams.predefinedAmounts.forEach(amount => {
+            query.append('predefinedAmounts', String(amount));
+        });
+    }
+    if (requestParams.layout != null) {
+        query.append('layout', requestParams.layout);
+    }
+    if (requestParams.fingerprint) {
+        query.append('fingerprint', requestParams.fingerprint);
+    }
+    const qs = query.toString();
+    return qs ? `?${qs}` : '';
+}
+function normalizePath(path) {
+    if (!path) {
+        return '/cashier';
+    }
+    return path.startsWith('/') ? path : `/${path}`;
+}
+function resolveContainer(container) {
+    if (container instanceof HTMLElement) {
+        return container;
+    }
+    if (typeof container === 'string') {
+        const target = document.querySelector(container);
+        if (target) {
+            return target;
+        }
+        console.warn(`Container selector "${container}" not found, defaulting to body`);
+    }
+    return document.body;
+}
+function buildIframeUrl(host, cashierPath, requestParams) {
+    const trimmedHost = host.endsWith('/') ? host.slice(0, -1) : host;
+    const path = normalizePath(cashierPath);
+    return `${trimmedHost}${path}${buildQueryString(requestParams)}`;
+}
+function getOriginFromUrl(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return '*';
+    }
+}
+export class CashierBootstrapper {
+    constructor(container, config = {}, onReady) {
+        this.origin = '*';
+        this.ready = false;
+        this.onReady = onReady;
+        const host = config.properties?.host;
+        if (!host) {
+            throw new Error('Cashier host is required to bootstrap the iframe');
+        }
+        this.fullConfig = {
+            requestParams: { ...config.requestParams },
+            properties: {
+                ...config.properties,
+                host,
+                cashierPath: normalizePath(config.properties?.cashierPath),
+                iframe: {
+                    width: '100%',
+                    height: '100%',
+                    allow: DEFAULT_IFRAME_ALLOW,
+                    ...config.properties?.iframe
+                }
+            }
+        };
+        const target = resolveContainer(container ?? this.fullConfig.properties.container);
+        this.iframe = this.createIframeShell(target);
+        void this.bootstrapIframe();
+    }
+    async bootstrapIframe() {
+        const fp = await generateFingerprint();
+        if (fp) {
+            this.fullConfig.requestParams.fingerprint = fp;
+        }
+        const src = buildIframeUrl(this.fullConfig.properties.host, this.fullConfig.properties.cashierPath ?? '/cashier', this.fullConfig.requestParams);
+        this.origin = getOriginFromUrl(src);
+        if (this.iframe) {
+            this.iframe.src = src;
+            this.iframe.onload = () => this.handleLoad();
+        }
+    }
+    createIframeShell(container) {
+        const iframe = document.createElement('iframe');
+        const { iframe: iframeOptions } = this.fullConfig.properties;
+        iframe.style.border = 'none';
+        iframe.style.width = iframeOptions?.width ?? '100%';
+        iframe.style.height = iframeOptions?.height ?? '100%';
+        if (iframeOptions?.minHeight) {
+            iframe.style.minHeight = iframeOptions.minHeight;
+        }
+        iframe.title = iframeOptions?.title ?? 'Cashier';
+        iframe.allow = iframeOptions?.allow ?? DEFAULT_IFRAME_ALLOW;
+        if (iframeOptions?.sandbox) {
+            iframe.setAttribute('sandbox', iframeOptions.sandbox);
+        }
+        if (iframeOptions?.attributes) {
+            Object.entries(iframeOptions.attributes).forEach(([key, value]) => iframe.setAttribute(key, value));
+        }
+        iframe.setAttribute('data-cashier-iframe', 'true');
+        iframe.setAttribute('data-cy', 'cashier-iframe');
+        container.innerHTML = '';
+        container.appendChild(iframe);
+        return iframe;
+    }
+    handleLoad() {
+        if (this.ready)
+            return;
+        this.ready = true;
+        if (this.onReady) {
+            this.onReady(this.api());
+        }
+    }
+    postMessage(eventType, payload) {
+        if (!this.iframe?.contentWindow) {
+            return;
+        }
+        this.iframe.contentWindow.postMessage({ eventType, payload }, this.origin);
+    }
+    /**
+     * API exposed to host pages for runtime control.
+     */
+    api() {
+        if (!this.iframe) {
+            throw new Error('Cashier iframe not initialized');
+        }
+        return {
+            iframe: this.iframe,
+            setCss: (css) => this.postMessage('SET_CSS', css),
+            updateData: (data) => this.postMessage('UPDATE_DATA', data),
+            pause: () => this.postMessage('CASHIER_PAUSE', {}),
+            resume: () => this.postMessage('CASHIER_RESUME', {})
+        };
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Cashier request parameters
+ */
+export interface CashierRequestParams {
+    merchantId?: string;
+    terminalId?: string;
+    userId?: string;
+    sessionId?: string;
+    predefinedAmounts?: number[];
+    layout?: string;
+    fingerprint?: string;
+}
+/**
+ * Bootstrap properties configuration
+ */
+export interface BootstrapProperties {
+    host: string;
+    /**
+     * Selector or element where HTML should be rendered
+     * Default: 'body' (replaces entire body)
+     */
+    container?: string | HTMLElement;
+}
+/**
+ * Bootstrap configuration combining request params and properties
+ */
+export interface CashierBootstrapConfig {
+    requestParams: CashierRequestParams;
+    properties: BootstrapProperties;
+}
+/**
+ * Additional iframe options for isolated embedding.
+ */
+export interface CashierIframeOptions {
+    /**
+     * Width of the iframe element. Default: '100%'.
+     */
+    width?: string;
+    /**
+     * Height of the iframe element. Default: '100%'.
+     */
+    height?: string;
+    /**
+     * Min height used to avoid layout jumps while cashier loads.
+     */
+    minHeight?: string;
+    /**
+     * Title attribute for accessibility.
+     */
+    title?: string;
+    /**
+     * Allow attribute controlling available browser features.
+     */
+    allow?: string;
+    /**
+     * Sandbox attribute if stricter isolation is desired.
+     */
+    sandbox?: string;
+    /**
+     * Extra attributes applied to the iframe element.
+     */
+    attributes?: Record<string, string>;
+}
+/**
+ * Properties for iframe embedding.
+ */
+export interface CashierIframeProperties extends BootstrapProperties {
+    /**
+     * Optional DOM container (selector or element) where the iframe is appended.
+     */
+    container?: string | HTMLElement;
+    /**
+     * Path to the cashier page. Default: '/cashier'.
+     */
+    cashierPath?: string;
+    /**
+     * Iframe tuning options (dimensions, attributes).
+     */
+    iframe?: CashierIframeOptions;
+}
+/**
+ * Config used by the iframe-based bootstrapper class.
+ */
+export interface CashierIframeConfig {
+    requestParams?: CashierRequestParams;
+    properties?: CashierIframeProperties;
+}
+/**
+ * Minimal API surface returned to hosts after iframe creation.
+ */
+export interface CashierIframeApi {
+    iframe: HTMLIFrameElement;
+    setCss: (css: string) => void;
+    updateData: (data: Record<string, unknown>) => void;
+    pause: () => void;
+    resume: () => void;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@morefin/cashier-bootstrapper",
+  "version": "0.1.0",
+  "description": "Bootstrap service for initializing cashier payment page data from API",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "morefin",
+    "cashier",
+    "payment",
+    "bootstrap",
+    "hosted-payment-page"
+  ],
+  "author": "",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.11.17",
+    "typescript": "^5.8.3"
+  }
+}