@paypercut/checkout-js 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Supported locales for Paypercut Checkout
+ *
+ * @remarks
+ * Single source of truth for all supported locale codes.
+ *
+ * Supported languages:
+ * - Bulgarian: 'bg', 'bg-BG'
+ * - English: 'en', 'en-GB'
+ * - Greek: 'el', 'el-GR'
+ * - Romanian: 'ro', 'ro-RO'
+ * - Croatian: 'hr', 'hr-HR'
+ * - Polish: 'pl', 'pl-PL'
+ * - Czech: 'cs', 'cs-CZ'
+ * - Slovenian: 'sl', 'sl-SI'
+ * - Slovak: 'sk', 'sk-SK'
+ *
+ * @example
+ * ```typescript
+ * const checkout = PaypercutCheckout({
+ *   locale: 'bg'  // or 'bg-BG', 'en', 'en-GB', etc.
+ * });
+ * ```
+ */
+declare const LOCALES: readonly ["bg", "bg-BG", "en", "en-GB", "el", "el-GR", "ro", "ro-RO", "hr", "hr-HR", "pl", "pl-PL", "cs", "cs-CZ", "sl", "sl-SI", "sk", "sk-SK"];
+/**
+ * Locale type - union of all supported locale codes plus 'auto'
+ * @example
+ * ```typescript
+ * const locale: Locale = 'bg';
+ * const autoLocale: Locale = 'auto';
+ * ```
+ */
+type Locale = typeof LOCALES[number] | 'auto';
+
+/**
+ * UI mode for checkout
+ */
+declare enum UIMode {
+    /** Custom UI mode - merchant provides their own submit button */
+    CUSTOM = "custom",
+    /** Embedded mode - checkout embedded in merchant page */
+    EMBEDDED = "embedded",
+    /** Hosted mode - full-page checkout experience */
+    HOSTED = "hosted"
+}
+/**
+ * Payment method types
+ */
+declare enum PaymentMethod {
+    /** Card payment (credit/debit) */
+    CARD = "card"
+}
+/**
+ * Wallet options for digital wallets
+ */
+declare enum WalletOption {
+    /** Apple Pay */
+    APPLE_PAY = "apple_pay",
+    /** Google Pay */
+    GOOGLE_PAY = "google_pay"
+}
+/**
+ * Configuration options for PaypercutCheckout
+ */
+interface PaypercutCheckoutOptions {
+    /** Checkout session identifier (e.g., 'CHK_12345') */
+    id: string;
+    /** CSS selector or HTMLElement where iframe mounts (required) */
+    containerId: string | HTMLElement;
+    /**
+     * Optional: Custom hosted checkout URL (only available in internal builds)
+     * Production builds will ignore this option for security
+     */
+    hostedCheckoutUrl?: string;
+    /**
+     * Optional: Locale for checkout UI
+     * @default 'en'
+     */
+    locale?: Locale | string;
+    /**
+     * Optional: UI mode for checkout
+     */
+    ui_mode?: UIMode | `${UIMode}`;
+    /**
+     * Optional: Payment methods to enable
+     * @default ['card']
+     */
+    payment_methods?: (PaymentMethod | `${PaymentMethod}`)[];
+    /**
+     * Optional: Digital wallet options
+     * Can include both or just one
+     */
+    wallet_options?: (WalletOption | `${WalletOption}`)[];
+    /**
+     * Optional: Show only the payment form without header/footer
+     * @default false
+     */
+    form_only?: boolean;
+}
+/**
+ * Event names that can be emitted by the checkout
+ */
+type EventName = 'loaded' | 'success' | 'error';
+/**
+ * Checkout instance interface
+ */
+interface CheckoutInstance {
+    /** Mount and render the iframe into the container */
+    render(): void;
+    /** Submit payment - sends message to hosted checkout to confirm payment */
+    submit(): void;
+    /** Destroy instance and cleanup all listeners */
+    destroy(): void;
+    /** Subscribe to events. Returns unsubscribe function */
+    on(event: EventName, handler: (...args: any[]) => void): () => void;
+    /** Subscribe to event that auto-unsubscribes after first emission */
+    once(event: EventName, handler: (...args: any[]) => void): () => void;
+    /** Unsubscribe from events */
+    off(event: EventName, handler: (...args: any[]) => void): void;
+    /** Check if checkout is currently mounted */
+    isMounted(): boolean;
+}
+/**
+ * PaypercutCheckout static interface (callable and constructable)
+ */
+interface PaypercutCheckoutStatic {
+    /** Callable factory function */
+    (options: PaypercutCheckoutOptions): CheckoutInstance;
+    /** Constructor support */
+    new (options: PaypercutCheckoutOptions): CheckoutInstance;
+    /** SDK version */
+    version: string;
+}
+
+/**
+ * Factory function that works both as callable and constructable.
+ * Always returns a new CheckoutImpl instance - no prototype manipulation needed.
+ */
+declare const PaypercutCheckout: PaypercutCheckoutStatic;
+
+export { LOCALES, PaymentMethod, PaypercutCheckout, UIMode, WalletOption, PaypercutCheckout as default };
+export type { CheckoutInstance, EventName, Locale, PaypercutCheckoutOptions, PaypercutCheckoutStatic };

package/dist/index.mjs

@@ -0,0 +1,509 @@
+/**
+ * Simple event emitter for handling checkout events
+ * Supports subscribing, unsubscribing, and emitting events
+ */
+class Emitter {
+    constructor() {
+        this.handlers = new Map();
+    }
+    /**
+     * Subscribe to an event
+     * @param event - Event name to listen to
+     * @param handler - Callback function to execute when event is emitted
+     * @returns Unsubscribe function
+     */
+    on(event, handler) {
+        if (!this.handlers.has(event)) {
+            this.handlers.set(event, new Set());
+        }
+        this.handlers.get(event).add(handler);
+        // Return unsubscribe function
+        return () => this.off(event, handler);
+    }
+    /**
+     * Subscribe to an event that auto-unsubscribes after first emission
+     *
+     * Common use case: waiting for 'loaded' event or handling first 'success'.
+     * Without this helper, developers would need to manually unsubscribe inside
+     * their handler, which is error-prone and leads to memory leaks if forgotten.
+     *
+     * @param event - Event name to listen to
+     * @param handler - Callback function to execute when event is emitted
+     * @returns Unsubscribe function
+     */
+    once(event, handler) {
+        const wrappedHandler = (...args) => {
+            handler(...args);
+            this.off(event, wrappedHandler);
+        };
+        return this.on(event, wrappedHandler);
+    }
+    /**
+     * Unsubscribe from an event
+     * @param event - Event name to stop listening to
+     * @param handler - Callback function to remove
+     */
+    off(event, handler) {
+        this.handlers.get(event)?.delete(handler);
+    }
+    /**
+     * Emit an event with optional arguments
+     * @param event - Event name to emit
+     * @param args - Arguments to pass to event handlers
+     */
+    emit(event, ...args) {
+        this.handlers.get(event)?.forEach(h => {
+            try {
+                h(...args);
+            }
+            catch (err) {
+                console.error(`[Emitter] Error in ${event} handler:`, err);
+            }
+        });
+    }
+    /**
+     * Clear all event handlers
+     */
+    clear() {
+        this.handlers.clear();
+    }
+}
+
+/**
+ * Build-time configuration
+ *
+ * This file is processed at build time with different values for:
+ * - Production build (for merchants)
+ * - Internal build (for team development)
+ */
+/**
+ * Production configuration (for merchants)
+ */
+/**
+ * Internal configuration (for team development)
+ */
+const internalConfig = {
+    version: "1.0.0",
+    defaultCheckoutOrigin: 'https://buy.paypercut.io',
+    allowedOrigins: [
+        'https://buy.paypercut.io',
+        'http://localhost:3000',
+        'http://localhost:3001',
+        'http://127.0.0.1:3000',
+        'http://127.0.0.1:3001'
+    ],
+    allowOriginOverride: true // ← Team CAN override for testing
+};
+/**
+ * Active configuration (selected at build time)
+ */
+const config = internalConfig
+    ;
+/**
+ * Helper to check if origin is allowed
+ */
+function isOriginAllowed(origin) {
+    return config.allowedOrigins.includes(origin);
+}
+/**
+ * Get the checkout origin (with optional override for internal builds)
+ */
+function getCheckoutOrigin(override) {
+    // Only allow override in internal builds
+    if (override && config.allowOriginOverride) {
+        return override;
+    }
+    return config.defaultCheckoutOrigin;
+}
+
+/**
+ * Supported locales for Paypercut Checkout
+ *
+ * @remarks
+ * Single source of truth for all supported locale codes.
+ *
+ * Supported languages:
+ * - Bulgarian: 'bg', 'bg-BG'
+ * - English: 'en', 'en-GB'
+ * - Greek: 'el', 'el-GR'
+ * - Romanian: 'ro', 'ro-RO'
+ * - Croatian: 'hr', 'hr-HR'
+ * - Polish: 'pl', 'pl-PL'
+ * - Czech: 'cs', 'cs-CZ'
+ * - Slovenian: 'sl', 'sl-SI'
+ * - Slovak: 'sk', 'sk-SK'
+ *
+ * @example
+ * ```typescript
+ * const checkout = PaypercutCheckout({
+ *   locale: 'bg'  // or 'bg-BG', 'en', 'en-GB', etc.
+ * });
+ * ```
+ */
+const LOCALES = [
+    'bg', 'bg-BG',
+    'en', 'en-GB',
+    'el', 'el-GR',
+    'ro', 'ro-RO',
+    'hr', 'hr-HR',
+    'pl', 'pl-PL',
+    'cs', 'cs-CZ',
+    'sl', 'sl-SI',
+    'sk', 'sk-SK',
+];
+/**
+ * Fast runtime check using Set for O(1) lookup
+ * @internal
+ */
+const LOCALE_SET = new Set(LOCALES);
+/**
+ * Normalize and validate locale
+ *
+ * @param locale - Locale code to normalize
+ * @returns Normalized locale code or 'en' as fallback
+ *
+ * @remarks
+ * - 'auto' or empty → 'en'
+ * - Unsupported locale → 'en' with console warning
+ * - Supported locale → original value
+ *
+ * @example
+ * ```typescript
+ * normalizeLocale('auto')  // → 'en'
+ * normalizeLocale('bg')    // → 'bg'
+ * normalizeLocale('de')    // → 'en' (with warning)
+ * ```
+ */
+function normalizeLocale(locale) {
+    if (!locale || locale === 'auto')
+        return 'en';
+    if (LOCALE_SET.has(locale))
+        return locale;
+    console.warn(`[PaypercutCheckout] Locale "${locale}" is not supported. Falling back to "en".`);
+    return 'en';
+}
+
+/**
+ * UI mode for checkout
+ */
+var UIMode;
+(function (UIMode) {
+    /** Custom UI mode - merchant provides their own submit button */
+    UIMode["CUSTOM"] = "custom";
+    /** Embedded mode - checkout embedded in merchant page */
+    UIMode["EMBEDDED"] = "embedded";
+    /** Hosted mode - full-page checkout experience */
+    UIMode["HOSTED"] = "hosted";
+})(UIMode || (UIMode = {}));
+/**
+ * Type guard for UIMode
+ */
+function isValidUIMode(value) {
+    return Object.values(UIMode).includes(value);
+}
+/**
+ * Payment method types
+ */
+var PaymentMethod;
+(function (PaymentMethod) {
+    /** Card payment (credit/debit) */
+    PaymentMethod["CARD"] = "card";
+})(PaymentMethod || (PaymentMethod = {}));
+/**
+ * Type guard for PaymentMethod
+ */
+function isValidPaymentMethod(value) {
+    return Object.values(PaymentMethod).includes(value);
+}
+/**
+ * Wallet options for digital wallets
+ */
+var WalletOption;
+(function (WalletOption) {
+    /** Apple Pay */
+    WalletOption["APPLE_PAY"] = "apple_pay";
+    /** Google Pay */
+    WalletOption["GOOGLE_PAY"] = "google_pay";
+})(WalletOption || (WalletOption = {}));
+/**
+ * Type guard for WalletOption
+ */
+function isValidWalletOption(value) {
+    return Object.values(WalletOption).includes(value);
+}
+/**
+ * Validate payment methods array
+ */
+function validatePaymentMethods(methods) {
+    const validated = [];
+    for (const method of methods) {
+        if (isValidPaymentMethod(method)) {
+            validated.push(method);
+        }
+        else {
+            console.warn(`[PaypercutCheckout] Invalid payment method: "${method}". Skipping.`);
+        }
+    }
+    // Default to card if no valid methods
+    if (validated.length === 0) {
+        console.warn('[PaypercutCheckout] No valid payment methods provided. Defaulting to "card".');
+        validated.push(PaymentMethod.CARD);
+    }
+    return validated;
+}
+/**
+ * Validate wallet options array
+ */
+function validateWalletOptions(options) {
+    const validated = [];
+    for (const option of options) {
+        if (isValidWalletOption(option)) {
+            validated.push(option);
+        }
+        else {
+            console.warn(`[PaypercutCheckout] Invalid wallet option: "${option}". Skipping.`);
+        }
+    }
+    return validated;
+}
+/**
+ * Validate UI mode
+ */
+function validateUIMode(mode) {
+    if (!mode) {
+        return undefined;
+    }
+    if (isValidUIMode(mode)) {
+        return mode;
+    }
+    console.warn(`[PaypercutCheckout] Invalid ui_mode: "${mode}". Valid options: ${Object.values(UIMode).join(', ')}`);
+    return undefined;
+}
+
+/**
+ * Internal implementation of CheckoutInstance
+ */
+class CheckoutImpl {
+    constructor(options) {
+        this.options = options;
+        this.emitter = new Emitter();
+        this.mounted = false;
+        this.destroyed = false;
+        this.iframe = null;
+        // Bind message handler
+        this.messageHandler = this.onMessage.bind(this);
+        window.addEventListener('message', this.messageHandler);
+    }
+    /**
+     * Build the iframe source URL with query parameters
+     */
+    buildSrc() {
+        const baseUrl = getCheckoutOrigin(this.options.hostedCheckoutUrl);
+        const url = new URL(`/c/${this.options.id}`, baseUrl);
+        // Add locale parameter
+        if (this.options.locale) {
+            const normalizedLocale = normalizeLocale(this.options.locale);
+            url.searchParams.set('locale', normalizedLocale);
+        }
+        // Add ui_mode parameter
+        if (this.options.ui_mode) {
+            const validatedUIMode = validateUIMode(this.options.ui_mode);
+            if (validatedUIMode) {
+                url.searchParams.set('ui_mode', validatedUIMode);
+            }
+        }
+        // Add payment_methods parameters (repeated for each method)
+        if (this.options.payment_methods && this.options.payment_methods.length > 0) {
+            const validatedMethods = validatePaymentMethods(this.options.payment_methods);
+            validatedMethods.forEach(method => {
+                url.searchParams.append('payment_methods', method);
+            });
+        }
+        // Add wallet_options parameters (repeated for each wallet)
+        if (this.options.wallet_options && this.options.wallet_options.length > 0) {
+            const validatedWallets = validateWalletOptions(this.options.wallet_options);
+            validatedWallets.forEach(wallet => {
+                url.searchParams.append('wallet_options', wallet);
+            });
+        }
+        console.log('this.options', this.options);
+        if (this.options.form_only !== undefined) {
+            url.searchParams.set('form_only', String(this.options.form_only));
+        }
+        return url.toString();
+    }
+    /**
+     * Get the container element from selector or HTMLElement
+     */
+    getContainer() {
+        const container = typeof this.options.containerId === 'string'
+            ? document.querySelector(this.options.containerId)
+            : this.options.containerId;
+        if (!container) {
+            throw new Error(`Container not found: ${this.options.containerId}`);
+        }
+        return container;
+    }
+    /**
+     * Handle incoming postMessage events from iframe
+     */
+    onMessage(evt) {
+        // Validate origin against allowed origins (build-time whitelist)
+        if (!isOriginAllowed(evt.origin)) {
+            console.warn('[PaypercutCheckout] Rejected message from unauthorized origin:', evt.origin, 'Allowed:', config.allowedOrigins);
+            return;
+        }
+        // Validate structure
+        const data = evt.data;
+        if (!data || typeof data !== 'object' || !('type' in data)) {
+            return;
+        }
+        // Filter messages by checkout session ID to prevent cross-instance message handling
+        // This ensures each checkout instance only processes its own messages
+        if (data.checkoutId && data.checkoutId !== this.options.id) {
+            return; // Message is for a different checkout instance
+        }
+        // Handle specific events
+        switch (data.type) {
+            case 'CHECKOUT_LOADED':
+                this.emitter.emit('loaded');
+                break;
+            case 'CHECKOUT_SUCCESS':
+                this.emitter.emit('success');
+                break;
+            case 'CHECKOUT_ERROR':
+                this.emitter.emit('error');
+                break;
+        }
+    }
+    /**
+     * Render the checkout iframe into the container
+     */
+    render() {
+        if (this.mounted) {
+            console.warn('[PaypercutCheckout] Already mounted');
+            return;
+        }
+        try {
+            const container = this.getContainer();
+            // Create iframe
+            this.iframe = document.createElement('iframe');
+            this.iframe.id = 'paypercut-checkout-iframe';
+            this.iframe.src = this.buildSrc();
+            this.iframe.allow = 'payment *; clipboard-write';
+            this.iframe.setAttribute('frameborder', '0');
+            // Apply default styles - just construct URL and assign to iframe
+            Object.assign(this.iframe.style, {
+                width: '100%',
+                height: '100%',
+                border: 'none',
+                display: 'block'
+            });
+            // Listen for iframe load event (fallback)
+            // This ensures 'loaded' event is always emitted even if hosted checkout
+            // doesn't send CHECKOUT_LOADED message
+            /*this.iframe.addEventListener('load', () => {
+              this.emitter.emit('loaded');
+            });*/
+            container.appendChild(this.iframe);
+            this.mounted = true;
+        }
+        catch (err) {
+            console.error('[PaypercutCheckout] Failed to render:', err);
+            throw err;
+        }
+    }
+    /**
+     * Submit payment - sends message to hosted checkout to confirm payment
+     */
+    submit() {
+        if (!this.mounted) {
+            console.warn('[PaypercutCheckout] Cannot submit: checkout not mounted');
+            return;
+        }
+        try {
+            this.postToIframe({
+                type: 'START_PROCESSING',
+                checkoutId: this.options.id,
+            });
+            console.log('[PaypercutCheckout] Submit payment message sent');
+        }
+        catch (err) {
+            console.error('[PaypercutCheckout] Failed to submit payment:', err);
+            throw err;
+        }
+    }
+    /**
+     * Send message to iframe - used for submit and other commands
+     */
+    postToIframe(message) {
+        if (!this.iframe?.contentWindow) {
+            console.error('[PaypercutCheckout] Cannot post message: iframe not mounted');
+            return;
+        }
+        const checkoutOrigin = getCheckoutOrigin(this.options.hostedCheckoutUrl);
+        this.iframe.contentWindow.postMessage(message, checkoutOrigin);
+    }
+    /**
+     * Destroy the checkout instance and cleanup (idempotent)
+     */
+    destroy() {
+        // Early return if already destroyed
+        if (this.destroyed) {
+            return;
+        }
+        // Remove iframe from DOM
+        if (this.iframe) {
+            try {
+                this.iframe.remove();
+                this.iframe = null;
+            }
+            catch (err) {
+                console.error('[PaypercutCheckout] Error removing iframe:', err);
+            }
+        }
+        // Only set mounted = false after successful DOM removal
+        this.mounted = false;
+        this.destroyed = true;
+        // Cleanup event listeners
+        window.removeEventListener('message', this.messageHandler);
+        this.emitter.clear();
+    }
+    /**
+     * Subscribe to an event
+     */
+    on(event, handler) {
+        return this.emitter.on(event, handler);
+    }
+    /**
+     * Subscribe to event that auto-unsubscribes after first emission
+     */
+    once(event, handler) {
+        return this.emitter.once(event, handler);
+    }
+    /**
+     * Unsubscribe from an event
+     */
+    off(event, handler) {
+        this.emitter.off(event, handler);
+    }
+    /**
+     * Check if checkout is currently mounted
+     */
+    isMounted() {
+        return this.mounted;
+    }
+}
+/**
+ * Factory function that works both as callable and constructable.
+ * Always returns a new CheckoutImpl instance - no prototype manipulation needed.
+ */
+const PaypercutCheckout = function (options) {
+    // Always return a new instance, regardless of how it's called
+    return new CheckoutImpl(options);
+};
+// Add static version property
+PaypercutCheckout.version = config.version;
+
+export { LOCALES, PaymentMethod, PaypercutCheckout, UIMode, WalletOption, PaypercutCheckout as default };
+//# sourceMappingURL=index.mjs.map