@morefin/cashier-bootstrapper 0.1.9 → 0.3.0

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
@@ -115,11 +127,6 @@ Callback mapping:
 - `onCancel`: result status `CANCELLED`
 - `onValidationFailed`: `/validate` request failed; `message` is forwarded from cashier
 
-## Examples Folder
-
-- 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
 
 ### `new CashierBootstrapper(container, config?, onReady?)`
@@ -146,6 +153,7 @@ interface CashierRequestParams {
   predefinedAmounts?: number[];
   layout?: string;
   transactionType?: string;
+  attributes?: Record<string, unknown>;
 }
 
 type CashierEnvironment = 'production' | 'uat';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { CashierIframeApi, CashierIframeConfig } from './types';
-export type { CashierCallbacks, CashierEnvironment, CashierRequestParams, CashierIframeApi, CashierIframeConfig, CashierIframeProperties, CashierResultCallbackPayload, CashierValidationFailedPayload } from './types';
+export type { CashierCallbacks, CashierEnvironment, CashierRequestParams, CashierIframeApi, CashierIframeConfig, CashierIframeProperties, CashierResultCallbackPayload, CashierRedirectPayload, CashierValidationFailedPayload } from './types';
 type FingerprintJSGlobal = {
     load: () => Promise<{
         get: () => Promise<{
@@ -39,6 +39,13 @@ export declare class CashierBootstrapper {
     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;

package/dist/index.js

@@ -92,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}` : '';
 }
@@ -288,31 +291,53 @@ export class CashierBootstrapper {
         if (!payload || typeof payload !== 'object') {
             return;
         }
-        const redirectUrl = payload.url;
-        const redirectTarget = this.normalizeRedirectTarget(payload.target);
+        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 });
-                if (!this.openProviderRedirectOverlay(redirectUrl) && this.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.');
-                    this.iframe.src = redirectUrl;
+                    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 });
-                window.open(redirectUrl, '_blank', 'noopener,noreferrer');
+                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 });
-                window.location.assign(redirectUrl);
+                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) {
+    openProviderRedirectOverlay(redirectUrl, redirectMethod, redirectParameters) {
         if (typeof document === 'undefined' || typeof window === 'undefined') {
             return false;
         }
@@ -343,7 +368,11 @@ export class CashierBootstrapper {
             panel.style.flexDirection = 'column';
             panel.style.pointerEvents = 'auto';
             const iframe = document.createElement('iframe');
-            iframe.src = redirectUrl;
+            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%';
@@ -360,6 +389,13 @@ export class CashierBootstrapper {
             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) {
@@ -399,7 +435,87 @@ export class CashierBootstrapper {
         if (target === 'iframe' || target === 'tab' || target === 'window') {
             return target;
         }
-        return 'window';
+        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') {

package/dist/types.d.ts

@@ -9,6 +9,7 @@ export interface CashierRequestParams {
     predefinedAmounts?: number[];
     layout?: string;
     transactionType?: string;
+    attributes?: Record<string, unknown>;
 }
 export type CashierEnvironment = 'production' | 'uat' | 'local' | 'local4200';
 /**
@@ -101,6 +102,13 @@ export interface CashierResultCallbackPayload {
 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;

package/package.json

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