npm - flintn-checkout - Versions diffs - 0.0.9 → 0.0.11 - Mend

flintn-checkout 0.0.9 → 0.0.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md CHANGED Viewed

@@ -6,12 +6,14 @@ FlintN Payment SDK — Embed payment forms via iframe checkout or headless hoste
 ```bash
 npm install flintn-checkout
 ```
+> **Note:** for local/non-production use, pass `origin` (e.g. `origin: 'http://localhost:3000'`).
 ## Iframe Checkout
 Full checkout UI rendered inside a single iframe. Includes card form, express payments (Apple Pay, Google Pay, PayPal), and 3DS handling.
-### React
+**React**
 ```tsx
 import { useFlintNPayment } from 'flintn-checkout/react';
@@ -37,11 +39,12 @@ function Checkout() {
 }
 ```
-### Vanilla JavaScript
+**Vanilla JavaScript**
 ```javascript
-import { FlintNPayment } from 'flintn-checkout';
+import { createFlintNPayment } from 'flintn-checkout';
-const payment = new FlintNPayment({
+const payment = createFlintNPayment({
   config: {
     clientSessionId: 'your_client_session_id',
   },
@@ -60,11 +63,12 @@ const payment = new FlintNPayment({
 payment.mount('#payment-container');
-// Cleanup when done
-payment.unmount();
+// Later, when you want to tear the widget down (e.g. on route change):
+// payment.unmount();
 ```
-### HTML
+**HTML**
 ```html
 <!DOCTYPE html>
 <html>
@@ -75,9 +79,9 @@ payment.unmount();
   <div id="payment-container" style="max-width: 440px; margin: 0 auto;"></div>
   <script type="module">
-    import { FlintNPayment } from 'flintn-checkout';
+    import { createFlintNPayment } from 'flintn-checkout';
-    const payment = new FlintNPayment({
+    const payment = createFlintNPayment({
       config: {
         clientSessionId: 'your_client_session_id',
       },
@@ -107,7 +111,7 @@ Do **not** set a fixed `height` on the container — it will leave empty space b
 | Option | Type | Required | Default | Description |
 |--------|------|----------|---------|-------------|
 | `config` | `FlintNConfig` | Yes | — | Checkout configuration |
-| `onPayment` | `(result: PaymentResult) => void` | No | — | Card payment result callback |
+| `onPayment` | `(result: PaymentResult) => void` | No | — | Payment result callback (success, error, cancelled) |
 | `onReady` | `() => void` | No | — | Widget loaded and ready |
 | `onError` | `(error: PaymentError) => void` | No | — | SDK initialization error |
 | `debug` | `boolean` | No | `false` | Enable console debug logs |
@@ -138,7 +142,8 @@ Individual PCI-compliant input fields rendered as separate iframes. You control
 Each field (card number, expiry, CVV) is a separate iframe. Raw card data never touches your page.
-### React
+**React**
 ```tsx
 import { useState } from 'react';
 import { useFlintNFields } from 'flintn-checkout/react';
@@ -223,11 +228,12 @@ function CheckoutForm() {
 }
 ```
-### Vanilla JavaScript
+**Vanilla JavaScript**
 ```javascript
-import { FlintNFields } from 'flintn-checkout';
+import { createFlintNFields } from 'flintn-checkout';
-const fields = new FlintNFields({
+const fields = createFlintNFields({
   config: {
     clientSessionId: 'your_client_session_id',
     styles: {
@@ -255,8 +261,8 @@ if (validation.isValid) {
   const result = await fields.submit({ cardholderName: 'John Doe' });
 }
-// Cleanup
-fields.unmount();
+// Cleanup (call when you're done with the form)
+// fields.unmount();
 ```
 ### Hosted Fields Options (Vanilla JS)
@@ -494,15 +500,6 @@ useFlintNFields({
 });
 ```
-## Test Cards
-| Card Number | Result |
-|-------------|--------|
-| `4111 1111 1111 1111` | Success |
-| `4000 0000 0000 0002` | Declined |
-Use any future expiry date and any 3-digit CVV.
 ## Browser Support
 - Chrome (latest)

package/dist/index.d.mts CHANGED Viewed

@@ -2,7 +2,6 @@ declare const EventType: {
     readonly WIDGET_READY: "WIDGET_READY";
     readonly WIDGET_CONFIG: "WIDGET_CONFIG";
     readonly PAYMENT: "PAYMENT";
-    readonly EXPRESS_PAYMENT: "EXPRESS_PAYMENT";
     readonly PAYMENT_SUCCESS: "PAYMENT_SUCCESS";
     readonly PAYMENT_ERROR: "PAYMENT_ERROR";
     readonly PAYMENT_CANCELLED: "PAYMENT_CANCELLED";
@@ -62,7 +61,6 @@ interface FlintNPaymentOptions {
     origin?: string;
     config: FlintNConfig;
     onPayment?: (result: PaymentResult) => void;
-    onExpressPayment?: (result: PaymentResult) => void;
     onReady?: () => void;
     onError?: (error: PaymentError) => void;
     debug?: boolean;
@@ -147,6 +145,7 @@ interface FlintNFieldInternalCallbacks {
     onFocus: (fieldType: TFieldType) => void;
     onBlur: (fieldType: TFieldType, state: FieldState) => void;
     onHeight: (fieldType: TFieldType, height: number) => void;
+    onError?: (err: Error) => void;
 }
 interface FlintNField {
     mount(selector: string | HTMLElement): void;

package/dist/index.d.ts CHANGED Viewed

@@ -2,7 +2,6 @@ declare const EventType: {
     readonly WIDGET_READY: "WIDGET_READY";
     readonly WIDGET_CONFIG: "WIDGET_CONFIG";
     readonly PAYMENT: "PAYMENT";
-    readonly EXPRESS_PAYMENT: "EXPRESS_PAYMENT";
     readonly PAYMENT_SUCCESS: "PAYMENT_SUCCESS";
     readonly PAYMENT_ERROR: "PAYMENT_ERROR";
     readonly PAYMENT_CANCELLED: "PAYMENT_CANCELLED";
@@ -62,7 +61,6 @@ interface FlintNPaymentOptions {
     origin?: string;
     config: FlintNConfig;
     onPayment?: (result: PaymentResult) => void;
-    onExpressPayment?: (result: PaymentResult) => void;
     onReady?: () => void;
     onError?: (error: PaymentError) => void;
     debug?: boolean;
@@ -147,6 +145,7 @@ interface FlintNFieldInternalCallbacks {
     onFocus: (fieldType: TFieldType) => void;
     onBlur: (fieldType: TFieldType, state: FieldState) => void;
     onHeight: (fieldType: TFieldType, height: number) => void;
+    onError?: (err: Error) => void;
 }
 interface FlintNField {
     mount(selector: string | HTMLElement): void;

package/dist/index.js CHANGED Viewed

@@ -40,7 +40,6 @@ var EventType = {
   WIDGET_READY: "WIDGET_READY",
   WIDGET_CONFIG: "WIDGET_CONFIG",
   PAYMENT: "PAYMENT",
-  EXPRESS_PAYMENT: "EXPRESS_PAYMENT",
   PAYMENT_SUCCESS: "PAYMENT_SUCCESS",
   PAYMENT_ERROR: "PAYMENT_ERROR",
   PAYMENT_CANCELLED: "PAYMENT_CANCELLED",
@@ -112,15 +111,38 @@ var sanitizeToken = (token) => {
 // src/flintn-payment.ts
 var DEFAULT_ORIGIN = "https://pay.flintn.com";
 function createFlintNPayment(options) {
-  validateConfig(options.config);
-  const origin = parseOrigin(options.origin || DEFAULT_ORIGIN);
+  const log = (...args) => {
+    if (options.debug) console.log("[FlintN SDK]", ...args);
+  };
+  const reportInitError = (err) => {
+    const error = {
+      code: "INIT_ERROR",
+      message: err instanceof Error ? err.message : "Failed to initialize SDK"
+    };
+    queueMicrotask(() => {
+      if (options.onError) options.onError(error);
+      else console.error("[FlintN SDK]", error);
+    });
+  };
+  let origin;
+  try {
+    validateConfig(options.config);
+    origin = parseOrigin(options.origin || DEFAULT_ORIGIN);
+  } catch (err) {
+    reportInitError(err);
+    return {
+      mount() {
+      },
+      unmount() {
+      },
+      getIsReady: () => false
+    };
+  }
   let iframe = null;
   let container = null;
   let isReady = false;
   let messageHandler = null;
-  const log = (...args) => {
-    if (options.debug) console.log("[FlintN SDK]", ...args);
-  };
+  let iframeErrorHandler = null;
   log("Initialized with origin:", origin);
   const sendConfig = () => {
     if (!iframe?.contentWindow) return;
@@ -130,10 +152,6 @@ function createFlintNPayment(options) {
     );
     log("Sent config:", sanitizeToken(options.config.clientSessionId));
   };
-  const handlePaymentResult = (payload, callback) => {
-    if (!callback) return;
-    callback(payload);
-  };
   const isValidRedirectUrl = (url) => {
     try {
       const parsed = new URL(url);
@@ -166,10 +184,7 @@ function createFlintNPayment(options) {
         options.onReady?.();
         break;
       case EventType.PAYMENT:
-        handlePaymentResult(payload, options.onPayment);
-        break;
-      case EventType.EXPRESS_PAYMENT:
-        handlePaymentResult(payload, options.onExpressPayment);
+        options.onPayment?.(payload);
         break;
       case EventType.REDIRECT:
         if (payload?.url && isValidRedirectUrl(payload.url)) {
@@ -186,12 +201,13 @@ function createFlintNPayment(options) {
   const mount = (selector) => {
     container = typeof selector === "string" ? document.querySelector(selector) : selector;
     if (!container) {
-      const selectorDescription = typeof selector === "string" ? selector : `<${selector.tagName.toLowerCase()}${selector.id ? ` id="${selector.id}"` : ""}${selector.className ? ` class="${selector.className}"` : ""}>`;
-      throw new Error(
-        `[FlintN SDK] Container not found: ${selectorDescription}`
-      );
+      const description = typeof selector === "string" ? selector : `<${selector.tagName.toLowerCase()}>`;
+      reportInitError(new Error(`Container not found: ${description}`));
+      return;
     }
     iframe = createIframeElement(buildIframeSrc(origin));
+    iframeErrorHandler = () => reportInitError(new Error("Failed to load checkout iframe"));
+    iframe.addEventListener("error", iframeErrorHandler);
     container.appendChild(iframe);
     messageHandler = handleMessage;
     window.addEventListener("message", messageHandler);
@@ -202,15 +218,19 @@ function createFlintNPayment(options) {
       window.removeEventListener("message", messageHandler);
       messageHandler = null;
     }
+    if (iframe && iframeErrorHandler) {
+      iframe.removeEventListener("error", iframeErrorHandler);
+      iframeErrorHandler = null;
+    }
     if (iframe && container && container.contains(iframe)) {
       container.removeChild(iframe);
     }
     iframe = null;
+    container = null;
     isReady = false;
     log("Unmounted");
   };
-  const getIsReady = () => isReady;
-  return { mount, unmount, getIsReady };
+  return { mount, unmount, getIsReady: () => isReady };
 }
 // src/flintn-field.ts
@@ -221,6 +241,7 @@ var FIELD_TITLES = {
 };
 function createFlintNField(fieldType, origin, clientSessionId, options, callbacks, debug = false, formStyles) {
   let iframe = null;
+  let iframeErrorHandler = null;
   let container = null;
   let state = {
     isEmpty: true,
@@ -231,6 +252,14 @@ function createFlintNField(fieldType, origin, clientSessionId, options, callback
   const log = (...args) => {
     if (debug) console.log(`[FlintN SDK][${fieldType}]`, ...args);
   };
+  const reportError = (err) => {
+    const error = err instanceof Error ? err : new Error(String(err));
+    if (callbacks.onError) {
+      queueMicrotask(() => callbacks.onError(error));
+    } else {
+      console.error(`[FlintN SDK][${fieldType}]`, error);
+    }
+  };
   const sendMessage = (type, payload) => {
     if (!iframe?.contentWindow) return;
     iframe.contentWindow.postMessage({ type, payload }, origin);
@@ -258,18 +287,35 @@ function createFlintNField(fieldType, origin, clientSessionId, options, callback
   const mount = (selector) => {
     container = typeof selector === "string" ? document.querySelector(selector) : selector;
     if (!container) {
-      throw new Error(
-        `[FlintN SDK] Field container not found for "${fieldType}": ${typeof selector === "string" ? selector : "element"}`
+      reportError(
+        new Error(
+          `Field container not found for "${fieldType}": ${typeof selector === "string" ? selector : "element"}`
+        )
       );
+      return;
     }
-    const src = buildIframeSrc(origin) + fieldType;
-    iframe = createIframeElement2(src);
+    try {
+      const src = buildIframeSrc(origin) + fieldType;
+      iframe = createIframeElement2(src);
+    } catch (err) {
+      reportError(err);
+      return;
+    }
+    iframeErrorHandler = () => {
+      reportError(new Error(`Failed to load ${fieldType} iframe`));
+    };
+    iframe.addEventListener("error", iframeErrorHandler);
     container.appendChild(iframe);
     log("Mounted", fieldType);
   };
   const unmount = () => {
+    if (iframe && iframeErrorHandler) {
+      iframe.removeEventListener("error", iframeErrorHandler);
+      iframeErrorHandler = null;
+    }
     if (iframe && container?.contains(iframe)) container.removeChild(iframe);
     iframe = null;
+    container = null;
     state = { isEmpty: true, isValid: false, isFocused: false, error: null };
     log("Unmounted", fieldType);
   };
@@ -333,11 +379,46 @@ function createFlintNField(fieldType, origin, clientSessionId, options, callback
 // src/flintn-fields.ts
 var DEFAULT_ORIGIN2 = "https://pay.flintn.com";
 var OPERATION_TIMEOUT = 3e4;
+function createInertFields() {
+  const errorResult = {
+    status: "PAYMENT_ERROR",
+    error: { code: "INIT_ERROR", message: "SDK init failed" }
+  };
+  return {
+    createField: () => {
+      throw new Error(
+        "[FlintN SDK] Cannot create field \u2014 SDK init failed (see onError)"
+      );
+    },
+    getField: () => void 0,
+    validate: async () => ({ isValid: false, errors: {} }),
+    submit: async () => errorResult,
+    unmount: () => {
+    },
+    getIsReady: () => false
+  };
+}
 function createFlintNFields(options) {
-  if (!options.config?.clientSessionId) {
-    throw new Error("[FlintN SDK] config.clientSessionId is required");
+  const reportInitError = (err) => {
+    const error = {
+      code: "INIT_ERROR",
+      message: err instanceof Error ? err.message : "Failed to initialize fields"
+    };
+    queueMicrotask(() => {
+      if (options.onError) options.onError(error);
+      else console.error("[FlintN SDK]", error);
+    });
+  };
+  let origin;
+  try {
+    if (!options.config?.clientSessionId) {
+      throw new Error("config.clientSessionId is required");
+    }
+    origin = parseOrigin(options.origin || DEFAULT_ORIGIN2);
+  } catch (err) {
+    reportInitError(err);
+    return createInertFields();
   }
-  const origin = parseOrigin(options.origin || DEFAULT_ORIGIN2);
   const fields = /* @__PURE__ */ new Map();
   const readyFields = /* @__PURE__ */ new Set();
   let allReady = false;
@@ -438,7 +519,8 @@ function createFlintNFields(options) {
         onFocus: onFieldFocus,
         onBlur: onFieldBlur,
         onHeight: () => {
-        }
+        },
+        onError: reportInitError
       },
       options.debug,
       options.config.styles
@@ -467,12 +549,22 @@ function createFlintNFields(options) {
   };
   const submit = async (submitOptions = {}, skipValidation = false) => {
     if (!fields.has(FieldType.CARD_NUMBER)) {
-      throw new Error(
-        '[FlintN SDK] card-number field not initialized. Call createField("card-number") before submit().'
-      );
+      return {
+        status: "PAYMENT_ERROR",
+        error: {
+          code: "CARD_NUMBER_NOT_INITIALIZED",
+          message: 'card-number field not initialized. Call createField("card-number") before submit().'
+        }
+      };
     }
     if (pendingSubmit) {
-      throw new Error("[FlintN SDK] A submit is already in progress");
+      return {
+        status: "PAYMENT_ERROR",
+        error: {
+          code: "SUBMIT_IN_PROGRESS",
+          message: "A submit is already in progress"
+        }
+      };
     }
     if (!skipValidation) {
       const validation = await validate();
@@ -489,17 +581,24 @@ function createFlintNFields(options) {
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         if (pendingSubmit && pendingSubmit.timer === timer) {
-          pendingSubmit.reject(new Error("[FlintN SDK] Submit timed out"));
+          const timeoutResult = {
+            status: "PAYMENT_ERROR",
+            error: {
+              code: "SUBMIT_TIMEOUT",
+              message: "Submit timed out"
+            }
+          };
+          pendingSubmit.resolve(timeoutResult);
+          options.onPayment?.(timeoutResult);
           pendingSubmit = null;
         }
       }, OPERATION_TIMEOUT);
       pendingSubmit = { resolve, reject, timer };
-      for (const field of fields.values()) {
-        field._sendMessage(FieldEventType.FIELD_SUBMIT, {
-          clientSessionId: options.config.clientSessionId,
-          cardholderName: submitOptions.cardholderName
-        });
-      }
+      const coordinator = fields.get(FieldType.CARD_NUMBER);
+      coordinator?._sendMessage(FieldEventType.FIELD_SUBMIT, {
+        clientSessionId: options.config.clientSessionId,
+        cardholderName: submitOptions.cardholderName
+      });
       log("Submit initiated");
     });
   };