@verbb/formie-browser 1.0.0

package/src/js/modules/payments/payment.ts

@@ -0,0 +1,183 @@
+import type { FormieModuleDefinition } from '#contracts/modules';
+
+type PaymentProviderConfig = {
+    handle: string;
+    requiredInputSuffixes: string[];
+    waitForValueMs: number;
+    errorMessage?: string;
+};
+
+const DEFAULT_WAIT_FOR_VALUE_MS = 2500;
+
+const DEFAULT_PROVIDER_SUFFIXES: Record<string, string[]> = {
+    stripe: ['stripePaymentIntentId'],
+    paypal: ['paypalOrderId'],
+    payway: ['paywayTokenId'],
+    opayo: ['opayoTokenId'],
+};
+
+function normalizeProviders(rawProviders: unknown, fallbackSuffixes: string[]): PaymentProviderConfig[] {
+    if (!Array.isArray(rawProviders) || rawProviders.length === 0) {
+        return [{
+            handle: 'generic',
+            requiredInputSuffixes: fallbackSuffixes,
+            waitForValueMs: DEFAULT_WAIT_FOR_VALUE_MS,
+        }];
+    }
+
+    return rawProviders.map((item) => {
+        if (typeof item === 'string') {
+            const normalizedHandle = item.trim();
+            return {
+                handle: normalizedHandle || 'unknown',
+                requiredInputSuffixes: DEFAULT_PROVIDER_SUFFIXES[normalizedHandle] || fallbackSuffixes,
+                waitForValueMs: DEFAULT_WAIT_FOR_VALUE_MS,
+            };
+        }
+
+        const raw = (item && typeof item === 'object' ? item : {}) as Record<string, unknown>;
+        const handle = String(raw.handle || '').trim();
+
+        return {
+            handle: handle || 'unknown',
+            requiredInputSuffixes: Array.isArray(raw.requiredInputSuffixes)
+                ? raw.requiredInputSuffixes.map(String)
+                : (DEFAULT_PROVIDER_SUFFIXES[handle] || fallbackSuffixes),
+            waitForValueMs: Number(raw.waitForValueMs || DEFAULT_WAIT_FOR_VALUE_MS),
+            errorMessage: typeof raw.errorMessage === 'string' ? raw.errorMessage : undefined,
+        };
+    }).filter((provider) => {
+        return provider.requiredInputSuffixes.length > 0;
+    });
+}
+
+function findInputBySuffix(root: Element, suffix: string): HTMLInputElement | null {
+    const escapedSuffix = suffix.replace(/"/g, '\\"');
+    return (root.querySelector(`input[name$="[${escapedSuffix}]"]`) ||
+        root.querySelector(`input[name$="${escapedSuffix}"]`)) as HTMLInputElement | null;
+}
+
+function hasAllRequiredInputs(root: Element, requiredInputSuffixes: string[]): { ok: boolean; missingSuffix?: string } {
+    const missingSuffix = requiredInputSuffixes.find((suffix) => {
+        const input = findInputBySuffix(root, suffix);
+        return !input || String(input.value || '').trim() === '';
+    });
+
+    return {
+        ok: !missingSuffix,
+        missingSuffix,
+    };
+}
+
+async function waitForRequiredInputs(root: Element, requiredInputSuffixes: string[], waitForValueMs: number): Promise<{ ok: boolean; missingSuffix?: string }> {
+    const initial = hasAllRequiredInputs(root, requiredInputSuffixes);
+    if (initial.ok) {
+        return initial;
+    }
+
+    const deadline = Date.now() + Math.max(waitForValueMs, 0);
+
+    // Payment SDKs often populate hidden tokens asynchronously after the user
+    // clicks submit, so authorize waits briefly for those inputs to settle.
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => {
+            window.setTimeout(resolve, 120);
+        });
+
+        const current = hasAllRequiredInputs(root, requiredInputSuffixes);
+        if (current.ok) {
+            return current;
+        }
+    }
+
+    return hasAllRequiredInputs(root, requiredInputSuffixes);
+}
+
+export const paymentModule: FormieModuleDefinition = {
+    id: 'payment',
+    kind: 'payment',
+    match: () => true,
+    setup: async(ctx) => {
+        const targetRoot = ctx.scope === 'field' ? ctx.target : ctx.root;
+        const requiredInputSuffixes = Array.isArray(ctx.options?.requiredInputSuffixes)
+            ? (ctx.options?.requiredInputSuffixes as string[])
+            : [];
+        const providers = normalizeProviders(ctx.options?.providers, requiredInputSuffixes);
+
+        const hasPaymentField = !!targetRoot.querySelector('[data-formie-field-type="payment"]');
+
+        return {
+            destroy: () => {
+                void ctx.emit('formie:module:payment:destroy', {});
+            },
+            onBeforeStage: async(stageCtx) => {
+                if (stageCtx.stage !== 'authorize') {
+                    return;
+                }
+
+                if (stageCtx.action !== 'submit') {
+                    return;
+                }
+
+                if (!hasPaymentField) {
+                    return;
+                }
+
+                await ctx.emit('formie:payment:authorize:before', {
+                    action: stageCtx.action,
+                });
+
+                for (const provider of providers) {
+                    await ctx.emit('formie:payment:provider:authorize:before', {
+                        provider,
+                        action: stageCtx.action,
+                    });
+
+                    const result = await waitForRequiredInputs(
+                        targetRoot,
+                        provider.requiredInputSuffixes,
+                        provider.waitForValueMs
+                    );
+
+                    if (!result.ok) {
+                        // Abort before dispatch so the form never posts without the
+                        // provider-specific token the backend expects to finalize payment.
+                        const message = provider.errorMessage || 'Payment authorization is incomplete.';
+                        stageCtx.abort(message);
+
+                        await ctx.emit('formie:payment:provider:authorize:error', {
+                            reason: 'missing-payment-token',
+                            provider,
+                            action: stageCtx.action,
+                            missingSuffix: result.missingSuffix,
+                        });
+
+                        await ctx.emit('formie:payment:authorize:error', {
+                            reason: 'missing-payment-token',
+                            providerHandle: provider.handle,
+                            missingSuffix: result.missingSuffix,
+                            action: stageCtx.action,
+                        });
+
+                        return;
+                    }
+
+                    await ctx.emit('formie:payment:provider:authorize:after', {
+                        provider,
+                        action: stageCtx.action,
+                    });
+                }
+            },
+            onAfterStage: async(stageCtx, result) => {
+                if (stageCtx.stage !== 'authorize') {
+                    return;
+                }
+
+                await ctx.emit('formie:payment:authorize:after', {
+                    action: stageCtx.action,
+                    result,
+                });
+            },
+        };
+    },
+};

package/src/js/modules/payments/paypal.ts

@@ -0,0 +1,214 @@
+import paypalCss from '#theme/integrations/_paypal.css?inline';
+
+import { definePaymentModule } from '#modules/payments/api';
+import { ensureModuleStyles } from '#modules/styles';
+import { loadScriptAndEnsureGlobal } from '#utils/scripts';
+
+ensureModuleStyles('paypal', [paypalCss]);
+
+type PayPalButtonsInstance = {
+    close: () => void;
+};
+
+type PayPalActions = {
+    order: {
+        create: (config: Record<string, unknown>) => Promise<string>;
+        authorize: () => Promise<Record<string, unknown>>;
+    };
+};
+
+type PayPalButtonsOptions = {
+    env: string;
+    style: Record<string, unknown>;
+    createOrder: (data: unknown, actions: PayPalActions) => Promise<string>;
+    onCancel?: () => void;
+    onError: (err: Error) => void;
+    onApprove: (data: { orderID: string }, actions: PayPalActions) => Promise<void>;
+};
+
+type PayPalGlobal = {
+    Buttons: (options: PayPalButtonsOptions) => { render: (el: HTMLElement) => PayPalButtonsInstance };
+};
+
+type PayPalProviderOptions = {
+    clientId?: string;
+    useSandbox?: boolean;
+    currency?: string;
+    amountType?: string;
+    amountFixed?: number;
+    amountVariable?: string;
+    buttonLayout?: string;
+    buttonColor?: string;
+    buttonShape?: string;
+    buttonLabel?: string;
+    buttonTagline?: boolean;
+    buttonWidth?: number;
+    buttonHeight?: number;
+};
+
+const SCRIPT_ID = 'FORMIE_PAYPAL_SCRIPT';
+
+function extractAuthIdFromAuthorization(result: Record<string, unknown> | null): string {
+    if (!result) {
+        return '';
+    }
+
+    const purchaseUnits = (result.purchase_units || []) as Array<Record<string, unknown>>;
+    const payments = (purchaseUnits[0]?.payments || {}) as Record<string, unknown>;
+
+    const authorizations = (payments.authorizations || []) as Array<Record<string, unknown>>;
+    const captures = (payments.captures || []) as Array<Record<string, unknown>>;
+
+    const authId = String(authorizations[0]?.id || captures[0]?.id || '');
+
+    return authId.trim();
+}
+
+function getScriptUrl(clientId: string, currency: string): string {
+    const params = [
+        'intent=authorize',
+        `currency=${encodeURIComponent(currency)}`,
+        `client-id=${encodeURIComponent(clientId)}`,
+    ];
+
+    return `https://www.paypal.com/sdk/js?${params.join('&')}`;
+}
+
+export const paypalModule = definePaymentModule<PayPalProviderOptions, PayPalGlobal | null, PayPalButtonsInstance | null>({
+    id: 'paypal',
+    defaultRequiredInputSuffixes: ['paypalOrderId', 'paypalAuthId'],
+    load: async (ctx) => {
+        const { provider } = ctx.options;
+        const clientId = provider.clientId as string | undefined;
+
+        if (!clientId?.trim()) {
+            console.error('[formie] Missing clientId for PayPal.');
+
+            return null;
+        }
+
+        const currency = (provider.currency as string) || 'AUD';
+        const scriptUrl = getScriptUrl(clientId, currency);
+
+        await loadScriptAndEnsureGlobal<PayPalGlobal>('paypal', {
+            id: SCRIPT_ID,
+            src: scriptUrl,
+        });
+
+        return (window as unknown as { paypal: PayPalGlobal }).paypal;
+    },
+    mount: async (args) => {
+        const { api, field, services, options, provider } = args;
+        const placeholder = field.querySelector<HTMLElement>('[data-formie-paypal-button]');
+
+        if (!placeholder || !api) {
+            return null;
+        }
+
+        // Guard against duplicate mounts on the same placeholder.
+        if (placeholder.getAttribute('data-formie-paypal-rendered') === 'true') {
+            return null;
+        }
+
+        // Ensure a clean mount surface before rendering PayPal buttons.
+        placeholder.innerHTML = '';
+
+        const useSandbox = Boolean(provider.useSandbox);
+        const currencyResult = services.resolveCurrency({ value: provider.currency, defaultCurrency: 'AUD' });
+
+        if (!currencyResult.ok) {
+            services.addError(('error' in currencyResult) ? currencyResult.error : 'Invalid PayPal currency.');
+
+            return null;
+        }
+
+        const currency = currencyResult.value;
+
+        const style: Record<string, unknown> = {
+            layout: provider.buttonLayout || 'vertical',
+            color: provider.buttonColor || 'gold',
+            shape: provider.buttonShape || 'rect',
+            label: provider.buttonLabel || 'paypal',
+            width: provider.buttonWidth || 250,
+            height: provider.buttonHeight || 35,
+        };
+
+        if (style.layout === 'horizontal') {
+            style.tagline = provider.buttonTagline ?? true;
+        }
+
+        const paypalOptions: PayPalButtonsOptions = {
+            env: useSandbox ? 'sandbox' : 'production',
+            style,
+            createOrder: (_data, actions) => {
+                services.removeError();
+                const amountResult = services.resolveAmount({
+                    type: provider.amountType as string,
+                    fixed: provider.amountFixed,
+                    variable: provider.amountVariable as string,
+                });
+
+                if (!amountResult.ok) {
+                    const errorMessage = ('error' in amountResult) ? amountResult.error : 'Invalid PayPal amount.';
+                    services.addError(errorMessage);
+
+                    throw new Error(errorMessage);
+                }
+
+                return actions.order.create({
+                    intent: 'AUTHORIZE',
+                    application_context: { user_action: 'CONTINUE' },
+                    purchase_units: [{
+                        amount: {
+                            currency_code: currency,
+                            value: String(amountResult.value),
+                        },
+                    }],
+                });
+            },
+            onError: (err) => {
+                services.addError(err?.message || 'PayPal error.');
+            },
+            onApprove: async (data, actions) => {
+                try {
+                    const authorization = await actions.order.authorize();
+                    const authId = extractAuthIdFromAuthorization(authorization);
+
+                    services.updateInputs('paypalOrderId', data.orderID);
+                    services.updateInputs('paypalAuthId', authId || '');
+
+                    if (authId) {
+                        services.addSuccess('Payment authorized. Finalize the form to complete payment.');
+                    } else {
+                        // Allow submit to continue using order ID fallback on the backend.
+                        services.addSuccess('PayPal approval received. Finalizing payment on submit.');
+                    }
+                } catch {
+                    services.addError('Unable to authorize payment. Please try again.');
+                }
+            },
+        };
+
+        const buttons = api.Buttons(paypalOptions);
+        placeholder.setAttribute('data-formie-paypal-rendered', 'true');
+        const instance = buttons.render(placeholder);
+
+        return instance;
+    },
+    unmount: async (args) => {
+        if (args.widget?.close) {
+            args.widget.close();
+        }
+
+        const placeholder = args.field.querySelector<HTMLElement>('[data-formie-paypal-button]');
+        if (placeholder) {
+            placeholder.removeAttribute('data-formie-paypal-rendered');
+            placeholder.innerHTML = '';
+        }
+    },
+    onAfterSubmit: async ({ services }) => {
+        services.updateInputs(['paypalOrderId', 'paypalAuthId'], '');
+        services.removeSuccess();
+        services.removeError();
+    },
+});

package/src/js/modules/payments/payway.ts

@@ -0,0 +1,114 @@
+import paywayCss from '#theme/integrations/_payway.css?inline';
+
+import { definePaymentModule } from '#modules/payments/api';
+import { ensureModuleStyles } from '#modules/styles';
+import { loadScriptAndEnsureGlobal } from '#utils/scripts';
+
+ensureModuleStyles('payway', [paywayCss]);
+
+type PayWayFrame = {
+    getToken: (callback: (err: Error | null, data?: { singleUseTokenId: string }) => void) => void;
+    destroy: () => void;
+};
+
+type PayWayGlobal = {
+    createCreditCardFrame: (
+        opts: { layout: string; publishableApiKey: string; tokenMode: string },
+        callback: (err: Error | null, frame?: PayWayFrame) => void
+    ) => void;
+};
+
+type PayWayProviderOptions = {
+    publishableKey?: string;
+};
+
+const SCRIPT_ID = 'FORMIE_PAYWAY_SCRIPT';
+
+export const paywayModule = definePaymentModule<PayWayProviderOptions, null, PayWayFrame | null>({
+    id: 'payway',
+    defaultRequiredInputSuffixes: ['paywayTokenId'],
+    load: async (ctx) => {
+        const { provider } = ctx.options;
+        const publishableKey = provider.publishableKey as string | undefined;
+
+        if (!publishableKey?.trim()) {
+            console.error('[formie] Missing publishableKey for PayWay.');
+
+            return null;
+        }
+
+        await loadScriptAndEnsureGlobal<PayWayGlobal>('payway', {
+            id: SCRIPT_ID,
+            src: 'https://api.payway.com.au/rest/v1/payway.js',
+        });
+
+        return null;
+    },
+    mount: async (args) => {
+        const { field, services, options } = args;
+        const provider = options.provider as PayWayProviderOptions;
+        const placeholder = field.querySelector<HTMLElement>('[data-formie-payway-button]');
+
+        if (!placeholder) {
+            return null;
+        }
+
+        const payway = (window as unknown as { payway: PayWayGlobal }).payway;
+
+        if (!payway) {
+            return null;
+        }
+
+        return new Promise<PayWayFrame | null>((resolve) => {
+            payway.createCreditCardFrame({
+                layout: 'wide',
+                publishableApiKey: provider.publishableKey || '',
+                tokenMode: 'callback',
+            }, (err, frame) => {
+                if (err || !frame) {
+                    services.addError(err?.message || 'PayWay frame failed to load.');
+                    resolve(null);
+
+                    return;
+                }
+
+                resolve(frame);
+            });
+        });
+    },
+    unmount: async (args) => {
+        args.widget?.destroy();
+    },
+    onBeforeAuthorize: async (args) => {
+        const { widget, services } = args;
+
+        if (!widget) {
+            services.addError('PayWay card frame is not ready.');
+
+            return false;
+        }
+
+        return new Promise<boolean>((resolve) => {
+            widget.getToken((err, data) => {
+                if (err) {
+                    services.addError(err.message);
+                    resolve(false);
+
+                    return;
+                }
+
+                if (data?.singleUseTokenId) {
+                    services.updateInputs('paywayTokenId', data.singleUseTokenId);
+
+                    resolve(true);
+                } else {
+                    services.addError('Tokenization failed.');
+                    resolve(false);
+                }
+            });
+        });
+    },
+    onAfterSubmit: async ({ services }) => {
+        services.updateInputs('paywayTokenId', '');
+    },
+});

package/src/js/modules/payments/square.ts

@@ -0,0 +1,106 @@
+import { definePaymentModule } from '#modules/payments/api';
+import { loadScriptAndEnsureGlobal } from '#utils/scripts';
+
+type SquareCard = {
+    tokenize: () => Promise<{ status: string; token?: string; errors?: Array<{ message: string }> }>;
+    attach: (element: HTMLElement) => Promise<void>;
+};
+
+type SquarePayments = {
+    card: () => Promise<SquareCard>;
+};
+
+type SquareGlobal = {
+    payments: (applicationId: string, locationId: string) => SquarePayments;
+};
+
+type SquareProviderOptions = {
+    applicationId?: string;
+    locationId?: string;
+    environment?: string;
+};
+
+const SCRIPT_ID = 'FORMIE_SQUARE_SCRIPT';
+
+export const squareModule = definePaymentModule<SquareProviderOptions, SquareGlobal | null, SquareCard | null>({
+    id: 'square',
+    defaultRequiredInputSuffixes: ['squarePaymentId'],
+    load: async(ctx) => {
+        const { provider } = ctx.options;
+        const applicationId = provider.applicationId as string | undefined;
+        const locationId = provider.locationId as string | undefined;
+
+        if (!applicationId?.trim() || !locationId?.trim()) {
+            console.error('[formie] Missing applicationId or locationId for Square.');
+
+            return null;
+        }
+
+        const environment = provider.environment as string;
+        const src = environment === 'sandbox'
+            ? 'https://sandbox.web.squarecdn.com/v1/square.js'
+            : 'https://web.squarecdn.com/v1/square.js';
+
+        await loadScriptAndEnsureGlobal<SquareGlobal>('Square', {
+            id: SCRIPT_ID,
+            src,
+        });
+
+        return (window as unknown as { Square: SquareGlobal }).Square;
+    },
+    mount: async(args) => {
+        const { api, field, services, options } = args;
+        const provider = options.provider as SquareProviderOptions;
+        const placeholder = field.querySelector<HTMLElement>('[data-formie-square-button]');
+
+        if (!placeholder || !api) {
+            return null;
+        }
+
+        try {
+            const payments = api.payments(provider.applicationId || '', provider.locationId || '');
+            const card = await payments.card();
+
+            await card.attach(placeholder);
+
+            return card;
+        } catch (error) {
+            services.addError(error instanceof Error ? error.message : 'Unable to initialize payment.');
+
+            return null;
+        }
+    },
+    unmount: async() => {
+        // Square card doesn't expose destroy, detach handled by removing element
+    },
+    onBeforeAuthorize: async(args) => {
+        const { widget, services } = args;
+
+        if (!widget) {
+            services.addError('Square card is not ready.');
+
+            return false;
+        }
+
+        try {
+            const result = await widget.tokenize();
+
+            if (result.status === 'OK' && result.token) {
+                services.updateInputs('squarePaymentId', result.token);
+
+                return true;
+            }
+
+            services.addError(result.errors?.[0]?.message || 'Tokenization failed.');
+
+            return false;
+        } catch {
+            services.addError('Payment tokenization failed. Please try again.');
+
+            return false;
+        }
+    },
+    onAfterSubmit: async({ services }) => {
+        services.updateInputs('squarePaymentId', '');
+    },
+});