@morefin/cashier-bootstrapper 0.1.8 → 0.1.9

package/README.md

@@ -85,9 +85,39 @@ new CashierBootstrapper('#cashier-root', {
 });
 ```
 
+### Transaction Result Callbacks
+
+```typescript
+import { CashierBootstrapper } from '@morefin/cashier-bootstrapper';
+
+new CashierBootstrapper('#cashier-root', {
+  properties: { environment: CASHIER_ENVIRONMENT },
+  callbacks: {
+    onSuccess: ({ status, transactionId }) => {
+      console.log('Cashier success callback', status, transactionId);
+    },
+    onFailure: ({ status, message, transactionId }) => {
+      console.log('Cashier failure callback', status, message, transactionId);
+    },
+    onCancel: ({ status, transactionId }) => {
+      console.log('Cashier cancel callback', status, transactionId);
+    },
+    onValidationFailed: ({ message }) => {
+      console.log('Cashier validation failed callback', message);
+    }
+  }
+});
+```
+
+Callback mapping:
+- `onSuccess`: result status `APPROVED` or `DECLINED`
+- `onFailure`: result status `INVALID` (or explicit cashier error event)
+- `onCancel`: result status `CANCELLED`
+- `onValidationFailed`: `/validate` request failed; `message` is forwarded from cashier
+
 ## Examples Folder
 
-- `examples/npm` contains a minimal app that installs the package from npm and bundles it with esbuild.
+- Repository examples live in `../examples/cashier-bootstrapper` (outside this package directory), including `../examples/cashier-bootstrapper/npm`.
 - `src/example-usage.ts` contains additional snippets for reference.
 
 ## API
@@ -99,6 +129,7 @@ Iframe-based embed that loads the cashier URL and exposes runtime controls once
 **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.environment` is required.
+- `config.callbacks?: CashierCallbacks` - Host callback handlers for cashier result events.
 - `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
@@ -138,14 +169,23 @@ interface CashierIframeProperties {
 interface CashierIframeConfig {
   requestParams?: CashierRequestParams;
   properties?: CashierIframeProperties;
+  callbacks?: CashierCallbacks;
+}
+
+interface CashierResultCallbackPayload {
+  status?: string;
+  transactionId?: string;
+  message?: string;
 }
-```
 
-## Defaults
+interface CashierValidationFailedPayload {
+  message: string;
+}
 
-- Cashier path is fixed to `/cashier`
-- `environment: 'production'` resolves to `https://api.morefin.com`
-- `environment: 'uat'` resolves to `https://uat-api.morefin.com`
-- Iframe URL origin is validated to allow only `api.morefin.com` and `uat-api.morefin.com`
-- `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 *;`
+interface CashierCallbacks {
+  onSuccess?: (payload: CashierResultCallbackPayload) => void;
+  onFailure?: (payload: CashierResultCallbackPayload) => void;
+  onCancel?: (payload: CashierResultCallbackPayload) => void;
+  onValidationFailed?: (payload: CashierValidationFailedPayload) => void;
+}
+```

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { CashierIframeApi, CashierIframeConfig } from './types';
-export type { CashierEnvironment, CashierRequestParams, CashierIframeApi, CashierIframeConfig, CashierIframeProperties } from './types';
+export type { CashierCallbacks, CashierEnvironment, CashierRequestParams, CashierIframeApi, CashierIframeConfig, CashierIframeProperties, CashierResultCallbackPayload, CashierValidationFailedPayload } from './types';
 type FingerprintJSGlobal = {
     load: () => Promise<{
         get: () => Promise<{
@@ -14,16 +14,34 @@ declare global {
 }
 export declare class CashierBootstrapper {
     private iframe?;
+    private redirectOverlayElement?;
+    private redirectOverlayPanel?;
+    private redirectOverlayIframe?;
+    private overlayPositionSyncHandler?;
     private origin;
     private ready;
     private readonly fullConfig;
     private readonly host;
+    private readonly allowedHostnames;
     private readonly onReady?;
+    private readonly callbacks?;
+    private readonly messageListener;
     constructor(container: string | HTMLElement | null | undefined, config?: CashierIframeConfig, onReady?: (api: CashierIframeApi) => void);
     private bootstrapIframe;
     private createIframeShell;
     private handleLoad;
     private postMessage;
+    private handleIframeMessage;
+    private handleCashierResultEvent;
+    private handleCashierValidationFailedEvent;
+    private handleCashierRedirect;
+    private openProviderRedirectOverlay;
+    private closeProviderRedirectOverlay;
+    private syncProviderRedirectOverlayToCashierIframe;
+    private normalizeRedirectTarget;
+    private normalizeResultStatus;
+    private asString;
+    private invokeCallback;
     /**
      * API exposed to host pages for runtime control.
      */

package/dist/index.js

@@ -1,11 +1,29 @@
 const DEFAULT_IFRAME_ALLOW = 'geolocation *;camera *;payment *;clipboard-read *;clipboard-write *;autoplay *;microphone *;fullscreen *;accelerometer *;magnetometer *;gyroscope *;picture-in-picture *;otp-credentials *;';
 const CASHIER_PATH = '/cashier';
 const FINGERPRINT_CDN = 'https://cdn.jsdelivr.net/npm/@fingerprintjs/fingerprintjs@4/dist/fp.min.js';
-const CASHIER_HOSTS = {
-    production: 'https://api.morefin.com',
-    uat: 'https://uat-api.morefin.com'
+const CASHIER_REDIRECT_EVENT = 'CASHIER_REDIRECT';
+const TOP_URL_REPLACE_EVENT = 'TOP_URL_REPLACE';
+const CASHIER_IFRAME_OVERLAY_CLOSE_EVENT = 'CASHIER_IFRAME_OVERLAY_CLOSE';
+const CASHIER_RESULT_EVENT = 'CASHIER_RESULT';
+const CASHIER_VALIDATION_FAILED_EVENT = 'CASHIER_VALIDATION_FAILED';
+const CASHIER_ENVIRONMENT_CONFIG = {
+    production: {
+        host: 'https://api.morefin.com',
+        allowedHostnames: ['api.morefin.com']
+    },
+    uat: {
+        host: 'https://uat-api.morefin.com',
+        allowedHostnames: ['uat-api.morefin.com']
+    },
+    local: {
+        host: 'http://localhost:7082',
+        allowedHostnames: ['localhost', '127.0.0.1']
+    },
+    local4200: {
+        host: 'http://localhost:4200',
+        allowedHostnames: ['localhost', '127.0.0.1']
+    }
 };
-const ALLOWED_CASHIER_DOMAINS = new Set(['api.morefin.com', 'uat-api.morefin.com']);
 let fpLoaderPromise;
 function loadFingerprintLibrary() {
     if (typeof window === 'undefined') {
@@ -62,7 +80,7 @@ function buildQueryString(requestParams, fingerprint) {
     }
     if (Array.isArray(requestParams.predefinedAmounts)) {
         requestParams.predefinedAmounts.forEach(amount => {
-            query.append('predefined_amounts', String(amount));
+            query.append('predefinedAmounts', String(amount));
         });
     }
     if (requestParams.layout != null && requestParams.layout !== '' && requestParams.layout !== 'undefined') {
@@ -90,39 +108,43 @@ function resolveContainer(container) {
     }
     return document.body;
 }
-function resolveHost(environment) {
-    const host = CASHIER_HOSTS[environment];
-    if (!host) {
+function resolveEnvironmentConfig(environment) {
+    const config = CASHIER_ENVIRONMENT_CONFIG[environment];
+    if (!config) {
         throw new Error(`Unsupported cashier environment "${environment}"`);
     }
-    return host;
+    return config;
 }
-function parseAndVerifyCashierUrl(url) {
+function parseAndVerifyCashierUrl(url, allowedHostnames) {
     const parsedUrl = new URL(url);
-    if (!ALLOWED_CASHIER_DOMAINS.has(parsedUrl.hostname)) {
+    if (!allowedHostnames.includes(parsedUrl.hostname)) {
         throw new Error(`Cashier domain "${parsedUrl.hostname}" is not allowed`);
     }
     return parsedUrl;
 }
-function buildIframeUrl(host, requestParams, fingerprint) {
+function buildIframeUrl(host, requestParams, allowedHostnames, fingerprint) {
     const trimmedHost = host.endsWith('/') ? host.slice(0, -1) : host;
     const url = `${trimmedHost}${CASHIER_PATH}${buildQueryString(requestParams, fingerprint)}`;
-    parseAndVerifyCashierUrl(url);
+    parseAndVerifyCashierUrl(url, allowedHostnames);
     return url;
 }
-function getOriginFromUrl(url) {
-    return parseAndVerifyCashierUrl(url).origin;
+function getOriginFromUrl(url, allowedHostnames) {
+    return parseAndVerifyCashierUrl(url, allowedHostnames).origin;
 }
 export class CashierBootstrapper {
     constructor(container, config = {}, onReady) {
         this.origin = '*';
         this.ready = false;
+        this.messageListener = (event) => this.handleIframeMessage(event);
         this.onReady = onReady;
+        this.callbacks = config.callbacks;
         const environment = config.properties?.environment;
         if (!environment) {
             throw new Error('Cashier environment is required to bootstrap the iframe');
         }
-        this.host = resolveHost(environment);
+        const environmentConfig = resolveEnvironmentConfig(environment);
+        this.host = environmentConfig.host;
+        this.allowedHostnames = environmentConfig.allowedHostnames;
         this.fullConfig = {
             requestParams: { ...config.requestParams },
             properties: {
@@ -138,12 +160,15 @@ export class CashierBootstrapper {
         };
         const target = resolveContainer(container ?? this.fullConfig.properties.container);
         this.iframe = this.createIframeShell(target);
+        if (typeof window !== 'undefined') {
+            window.addEventListener('message', this.messageListener);
+        }
         void this.bootstrapIframe();
     }
     async bootstrapIframe() {
         const fp = await generateFingerprint();
-        const src = buildIframeUrl(this.host, this.fullConfig.requestParams, fp);
-        this.origin = getOriginFromUrl(src);
+        const src = buildIframeUrl(this.host, this.fullConfig.requestParams, this.allowedHostnames, fp);
+        this.origin = getOriginFromUrl(src, this.allowedHostnames);
         if (this.iframe) {
             this.iframe.src = src;
             this.iframe.onload = () => this.handleLoad();
@@ -186,6 +211,221 @@ export class CashierBootstrapper {
         }
         this.iframe.contentWindow.postMessage({ eventType, payload }, this.origin);
     }
+    handleIframeMessage(event) {
+        const sourceIsMainCashierIframe = !!this.iframe?.contentWindow && event.source === this.iframe.contentWindow;
+        const sourceIsOverlayIframe = !!this.redirectOverlayIframe?.contentWindow && event.source === this.redirectOverlayIframe.contentWindow;
+        if (!sourceIsMainCashierIframe && !sourceIsOverlayIframe) {
+            return;
+        }
+        if (event.origin !== this.origin) {
+            return;
+        }
+        if (!event.data || typeof event.data !== 'object') {
+            return;
+        }
+        const { eventType, payload } = event.data;
+        if (eventType === CASHIER_IFRAME_OVERLAY_CLOSE_EVENT) {
+            if (sourceIsOverlayIframe) {
+                this.closeProviderRedirectOverlay();
+            }
+            return;
+        }
+        if (!sourceIsMainCashierIframe) {
+            return;
+        }
+        if (eventType === TOP_URL_REPLACE_EVENT) {
+            this.handleCashierRedirect({ url: payload?.url, target: 'window' });
+            return;
+        }
+        if (eventType === CASHIER_RESULT_EVENT) {
+            this.handleCashierResultEvent(payload);
+            return;
+        }
+        if (eventType === CASHIER_VALIDATION_FAILED_EVENT) {
+            this.handleCashierValidationFailedEvent(payload);
+            return;
+        }
+        if (eventType === CASHIER_REDIRECT_EVENT) {
+            this.handleCashierRedirect(payload);
+        }
+    }
+    handleCashierResultEvent(payload) {
+        if (!payload || typeof payload !== 'object') {
+            return;
+        }
+        const resultPayload = payload;
+        const status = this.normalizeResultStatus(resultPayload['status']);
+        const callbackPayload = {
+            status,
+            transactionId: this.asString(resultPayload['transactionId']),
+            message: this.asString(resultPayload['message'])
+        };
+        if (!status) {
+            return;
+        }
+        if (status === 'approved' || status === 'declined') {
+            this.invokeCallback(this.callbacks?.onSuccess, callbackPayload);
+            return;
+        }
+        if (status === 'cancelled') {
+            this.invokeCallback(this.callbacks?.onCancel, callbackPayload);
+            return;
+        }
+        if (status === 'invalid' || status === 'error') {
+            this.invokeCallback(this.callbacks?.onFailure, callbackPayload);
+        }
+    }
+    handleCashierValidationFailedEvent(payload) {
+        if (!payload || typeof payload !== 'object') {
+            return;
+        }
+        const validationPayload = payload;
+        const message = this.asString(validationPayload['message']) ?? 'Validation failed';
+        const callbackPayload = { message };
+        this.invokeCallback(this.callbacks?.onValidationFailed, callbackPayload);
+    }
+    handleCashierRedirect(payload) {
+        if (!payload || typeof payload !== 'object') {
+            return;
+        }
+        const redirectUrl = payload.url;
+        const redirectTarget = this.normalizeRedirectTarget(payload.target);
+        if (typeof redirectUrl !== 'string' || redirectUrl.trim() === '') {
+            return;
+        }
+        switch (redirectTarget) {
+            case 'iframe':
+                console.log('[CashierBootstrapper] Handling redirect target "iframe".', { redirectUrl });
+                if (!this.openProviderRedirectOverlay(redirectUrl) && this.iframe) {
+                    console.warn('[CashierBootstrapper] Could not open provider overlay; falling back to redirect inside cashier iframe.');
+                    this.iframe.src = redirectUrl;
+                }
+                break;
+            case 'tab':
+                console.log('[CashierBootstrapper] Handling redirect target "tab".', { redirectUrl });
+                window.open(redirectUrl, '_blank', 'noopener,noreferrer');
+                break;
+            case 'window':
+            default:
+                console.log('[CashierBootstrapper] Handling redirect target "window".', { redirectUrl });
+                window.location.assign(redirectUrl);
+                break;
+        }
+    }
+    openProviderRedirectOverlay(redirectUrl) {
+        if (typeof document === 'undefined' || typeof window === 'undefined') {
+            return false;
+        }
+        if (!this.iframe) {
+            return false;
+        }
+        this.closeProviderRedirectOverlay();
+        try {
+            const overlay = document.createElement('div');
+            overlay.setAttribute('data-cashier-provider-overlay', 'true');
+            overlay.style.position = 'fixed';
+            overlay.style.top = '0';
+            overlay.style.left = '0';
+            overlay.style.right = '0';
+            overlay.style.bottom = '0';
+            overlay.style.zIndex = '2147483000';
+            overlay.style.background = 'transparent';
+            overlay.style.pointerEvents = 'none';
+            const panel = document.createElement('div');
+            panel.style.position = 'fixed';
+            panel.style.top = '0';
+            panel.style.left = '0';
+            panel.style.width = '0';
+            panel.style.height = '0';
+            panel.style.background = '#fff';
+            panel.style.overflow = 'hidden';
+            panel.style.display = 'flex';
+            panel.style.flexDirection = 'column';
+            panel.style.pointerEvents = 'auto';
+            const iframe = document.createElement('iframe');
+            iframe.src = redirectUrl;
+            iframe.style.border = 'none';
+            iframe.style.width = '100%';
+            iframe.style.height = '100%';
+            iframe.allow = DEFAULT_IFRAME_ALLOW;
+            iframe.setAttribute('data-provider-redirect-iframe', 'true');
+            panel.appendChild(iframe);
+            overlay.appendChild(panel);
+            document.body.appendChild(overlay);
+            this.redirectOverlayElement = overlay;
+            this.redirectOverlayPanel = panel;
+            this.redirectOverlayIframe = iframe;
+            this.syncProviderRedirectOverlayToCashierIframe();
+            const sync = () => this.syncProviderRedirectOverlayToCashierIframe();
+            this.overlayPositionSyncHandler = sync;
+            window.addEventListener('resize', sync);
+            window.addEventListener('scroll', sync, true);
+            return true;
+        }
+        catch (err) {
+            console.warn('Failed to mount provider redirect iframe overlay.', err);
+            this.closeProviderRedirectOverlay();
+            return false;
+        }
+    }
+    closeProviderRedirectOverlay() {
+        if (typeof window !== 'undefined' && this.overlayPositionSyncHandler) {
+            window.removeEventListener('resize', this.overlayPositionSyncHandler);
+            window.removeEventListener('scroll', this.overlayPositionSyncHandler, true);
+        }
+        this.overlayPositionSyncHandler = undefined;
+        const overlay = this.redirectOverlayElement;
+        if (overlay && overlay.parentNode) {
+            overlay.parentNode.removeChild(overlay);
+        }
+        this.redirectOverlayElement = undefined;
+        this.redirectOverlayPanel = undefined;
+        this.redirectOverlayIframe = undefined;
+    }
+    syncProviderRedirectOverlayToCashierIframe() {
+        const panel = this.redirectOverlayPanel;
+        const iframe = this.iframe;
+        if (!panel || !iframe) {
+            return;
+        }
+        const rect = iframe.getBoundingClientRect();
+        panel.style.left = `${rect.left}px`;
+        panel.style.top = `${rect.top}px`;
+        panel.style.width = `${rect.width}px`;
+        panel.style.height = `${rect.height}px`;
+        panel.style.borderRadius = window.getComputedStyle(iframe).borderRadius || '0';
+    }
+    normalizeRedirectTarget(target) {
+        if (target === 'iframe' || target === 'tab' || target === 'window') {
+            return target;
+        }
+        return 'window';
+    }
+    normalizeResultStatus(status) {
+        if (typeof status !== 'string') {
+            return undefined;
+        }
+        const normalized = status.trim().toLowerCase();
+        return normalized || undefined;
+    }
+    asString(value) {
+        if (typeof value !== 'string') {
+            return undefined;
+        }
+        const normalized = value.trim();
+        return normalized || undefined;
+    }
+    invokeCallback(callback, payload) {
+        if (!callback) {
+            return;
+        }
+        try {
+            callback(payload);
+        }
+        catch (err) {
+            console.error('[CashierBootstrapper] Host callback threw an error.', err);
+        }
+    }
     /**
      * API exposed to host pages for runtime control.
      */

package/dist/types.d.ts

@@ -10,7 +10,7 @@ export interface CashierRequestParams {
     layout?: string;
     transactionType?: string;
 }
-export type CashierEnvironment = 'production' | 'uat';
+export type CashierEnvironment = 'production' | 'uat' | 'local' | 'local4200';
 /**
  * Bootstrap properties configuration
  */
@@ -81,6 +81,7 @@ export interface CashierIframeProperties extends BootstrapProperties {
 export interface CashierIframeConfig {
     requestParams?: CashierRequestParams;
     properties?: CashierIframeProperties;
+    callbacks?: CashierCallbacks;
 }
 /**
  * Minimal API surface returned to hosts after iframe creation.
@@ -92,3 +93,17 @@ export interface CashierIframeApi {
     pause: () => void;
     resume: () => void;
 }
+export interface CashierResultCallbackPayload {
+    status?: string;
+    transactionId?: string;
+    message?: string;
+}
+export interface CashierValidationFailedPayload {
+    message: string;
+}
+export interface CashierCallbacks {
+    onSuccess?: (payload: CashierResultCallbackPayload) => void;
+    onFailure?: (payload: CashierResultCallbackPayload) => void;
+    onCancel?: (payload: CashierResultCallbackPayload) => void;
+    onValidationFailed?: (payload: CashierValidationFailedPayload) => void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morefin/cashier-bootstrapper",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Bootstrap service for initializing cashier payment page data from API",
   "main": "dist/index.js",
   "module": "dist/index.js",