@morefin/cashier-bootstrapper 0.1.8 → 0.2.9

package/README.md

@@ -39,14 +39,22 @@ new CashierBootstrapper('#cashier-root', {
     sessionId: 'session-abc',
     predefinedAmounts: [100, 200, 300],
     layout: 'default',
-    transactionType: ('deposit'|'withdrawal')
+    transactionType: ('deposit'|'withdrawal'),
+    attributes: {
+      channel: 'web',
+      campaign: 'spring-launch',
+      isVip: true
+    }
   },
   properties: {
     environment: CASHIER_ENVIRONMENT,
     iframe: {
       height: '720px',
       minHeight: '640px',
-      title: 'Morefin Cashier'
+      title: 'Morefin Cashier',
+      attributes: {
+        'data-testid': 'cashier-iframe'
+      }
     }
   }
 }, api => {
@@ -54,6 +62,10 @@ new CashierBootstrapper('#cashier-root', {
 });
 ```
 
+`requestParams.attributes` sends custom cashier data as the `attributes` query parameter. Use it for values the cashier should receive as part of the request payload.
+
+`properties.iframe.attributes` applies plain HTML attributes directly to the rendered `<iframe>`. Use it for DOM concerns such as `data-*`, `loading`, or other iframe element attributes.
+
 ### Provide Container via Config
 
 ```typescript
@@ -85,10 +97,35 @@ new CashierBootstrapper('#cashier-root', {
 });
 ```
 
-## Examples Folder
+### 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);
+    }
+  }
+});
+```
 
-- `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.
+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
 
 ## API
 
@@ -99,6 +136,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
@@ -115,6 +153,7 @@ interface CashierRequestParams {
   predefinedAmounts?: number[];
   layout?: string;
   transactionType?: string;
+  attributes?: Record<string, unknown>;
 }
 
 type CashierEnvironment = 'production' | 'uat';
@@ -138,14 +177,23 @@ interface CashierIframeProperties {
 interface CashierIframeConfig {
   requestParams?: CashierRequestParams;
   properties?: CashierIframeProperties;
+  callbacks?: CashierCallbacks;
 }
-```
 
-## Defaults
+interface CashierResultCallbackPayload {
+  status?: string;
+  transactionId?: string;
+  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 CashierValidationFailedPayload {
+  message: string;
+}
+
+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, CashierRedirectPayload, CashierValidationFailedPayload } from './types';
 type FingerprintJSGlobal = {
     load: () => Promise<{
         get: () => Promise<{
@@ -14,16 +14,41 @@ 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 normalizeRedirectMethod;
+    private normalizeRedirectParameters;
+    private openPopupWithPost;
+    private writePostFormToWindow;
+    private submitPostForm;
+    private buildPostHtml;
+    private escapeHtml;
+    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') {
@@ -74,6 +92,9 @@ function buildQueryString(requestParams, fingerprint) {
     if (requestParams.transactionType) {
         query.append('transactionType', requestParams.transactionType);
     }
+    if (requestParams.attributes) {
+        query.append('attributes', JSON.stringify(requestParams.attributes));
+    }
     const qs = query.toString();
     return qs ? `?${qs}` : '';
 }
@@ -90,39 +111,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 +163,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 +214,334 @@ 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 redirectPayload = payload;
+        const redirectUrl = redirectPayload.url;
+        const redirectTarget = this.normalizeRedirectTarget(redirectPayload.target);
+        const redirectMethod = this.normalizeRedirectMethod(redirectPayload.method);
+        const redirectParameters = this.normalizeRedirectParameters(redirectPayload.parameters);
+        if (typeof redirectUrl !== 'string' || redirectUrl.trim() === '') {
+            return;
+        }
+        switch (redirectTarget) {
+            case 'iframe':
+                console.log('[CashierBootstrapper] Handling redirect target "iframe".', { redirectUrl, redirectMethod, redirectParameters });
+                if (!this.openProviderRedirectOverlay(redirectUrl, redirectMethod, redirectParameters) && this.iframe) {
+                    console.warn('[CashierBootstrapper] Could not open provider overlay; falling back to redirect inside cashier iframe.');
+                    if (redirectMethod === 'POST' && !this.submitPostForm(redirectUrl, redirectParameters, '_self')) {
+                        this.iframe.src = redirectUrl;
+                    }
+                    else if (redirectMethod === 'GET') {
+                        this.iframe.src = redirectUrl;
+                    }
+                }
+                break;
+            case 'tab':
+                console.log('[CashierBootstrapper] Handling redirect target "tab".', { redirectUrl, redirectMethod, redirectParameters });
+                if (redirectMethod === 'POST') {
+                    if (!this.openPopupWithPost(redirectUrl, redirectParameters)) {
+                        this.submitPostForm(redirectUrl, redirectParameters, '_blank');
+                    }
+                }
+                else {
+                    window.open(redirectUrl, '_blank', 'noopener,noreferrer');
+                }
+                break;
+            case 'window':
+            default:
+                console.log('[CashierBootstrapper] Handling redirect target "window".', { redirectUrl, redirectMethod, redirectParameters });
+                if (redirectMethod === 'POST') {
+                    if (!this.openPopupWithPost(redirectUrl, redirectParameters)) {
+                        this.submitPostForm(redirectUrl, redirectParameters, '_self');
+                    }
+                }
+                else {
+                    window.location.assign(redirectUrl);
+                }
+                break;
+        }
+    }
+    openProviderRedirectOverlay(redirectUrl, redirectMethod, redirectParameters) {
+        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');
+            const iframeName = `provider-redirect-iframe-${Date.now()}`;
+            iframe.name = iframeName;
+            if (redirectMethod === 'GET') {
+                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);
+            if (redirectMethod === 'POST') {
+                const submitted = this.submitPostForm(redirectUrl, redirectParameters, iframeName, overlay);
+                if (!submitted) {
+                    this.closeProviderRedirectOverlay();
+                    return false;
+                }
+            }
+            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 'tab';
+    }
+    normalizeRedirectMethod(method) {
+        if (typeof method !== 'string') {
+            return 'GET';
+        }
+        const normalized = method.trim().toUpperCase();
+        return normalized === 'POST' ? 'POST' : 'GET';
+    }
+    normalizeRedirectParameters(parameters) {
+        if (!parameters || typeof parameters !== 'object') {
+            return {};
+        }
+        return Object.entries(parameters).reduce((acc, [key, value]) => {
+            acc[key] = String(value ?? '');
+            return acc;
+        }, {});
+    }
+    openPopupWithPost(url, parameters) {
+        if (typeof window === 'undefined') {
+            return false;
+        }
+        const popup = window.open('', '_blank');
+        if (!popup) {
+            return false;
+        }
+        return this.writePostFormToWindow(popup, url, parameters);
+    }
+    writePostFormToWindow(targetWindow, url, parameters) {
+        try {
+            targetWindow.document.open();
+            targetWindow.document.write(this.buildPostHtml(url, parameters, 'provider-redirect-form-window'));
+            targetWindow.document.close();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    submitPostForm(url, parameters, target, parent = document) {
+        try {
+            const doc = parent instanceof Document ? parent : parent.ownerDocument;
+            if (!doc || !doc.body) {
+                return false;
+            }
+            const form = doc.createElement('form');
+            form.method = 'post';
+            form.action = url;
+            form.target = target;
+            form.style.display = 'none';
+            Object.entries(parameters).forEach(([key, value]) => {
+                const input = doc.createElement('input');
+                input.type = 'hidden';
+                input.name = key;
+                input.value = value;
+                form.appendChild(input);
+            });
+            doc.body.appendChild(form);
+            form.submit();
+            form.remove();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    buildPostHtml(url, parameters, formName) {
+        const safeAction = this.escapeHtml(url);
+        const safeFormName = this.escapeHtml(formName);
+        const inputs = Object.entries(parameters)
+            .map(([key, value]) => `<input type="hidden" name="${this.escapeHtml(key)}" value="${this.escapeHtml(value)}">`)
+            .join('');
+        return `<!doctype html><html><head><meta charset="utf-8"></head><body><form id="${safeFormName}" name="${safeFormName}" method="post" action="${safeAction}">${inputs}</form><script>document.getElementById('${safeFormName}')?.submit();</script></body></html>`;
+    }
+    escapeHtml(value) {
+        return value
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&#39;');
+    }
+    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

@@ -9,8 +9,9 @@ export interface CashierRequestParams {
     predefinedAmounts?: number[];
     layout?: string;
     transactionType?: string;
+    attributes?: Record<string, unknown>;
 }
-export type CashierEnvironment = 'production' | 'uat';
+export type CashierEnvironment = 'production' | 'uat' | 'local' | 'local4200';
 /**
  * Bootstrap properties configuration
  */
@@ -81,6 +82,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 +94,24 @@ export interface CashierIframeApi {
     pause: () => void;
     resume: () => void;
 }
+export interface CashierResultCallbackPayload {
+    status?: string;
+    transactionId?: string;
+    message?: string;
+}
+export interface CashierValidationFailedPayload {
+    message: string;
+}
+export interface CashierRedirectPayload {
+    url: string;
+    target?: 'iframe' | 'window' | 'tab';
+    method?: 'GET' | 'POST';
+    parameters?: Record<string, string>;
+    transactionId?: 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.2.9",
   "description": "Bootstrap service for initializing cashier payment page data from API",
   "main": "dist/index.js",
   "module": "dist/index.js",