flintn-checkout 0.0.8 → 0.0.9

package/README.md

@@ -1,13 +1,15 @@
 # flintn-checkout
 
-FlintN Payment SDK — Iframe-based payment widget with postMessage communication.
+FlintN Payment SDK — Embed payment forms via iframe checkout or headless hosted fields.
 
 ## Installation
 ```bash
 npm install flintn-checkout
 ```
 
-## Quick Start
+## Iframe Checkout
+
+Full checkout UI rendered inside a single iframe. Includes card form, express payments (Apple Pay, Google Pay, PayPal), and 3DS handling.
 
 ### React
 ```tsx
@@ -25,9 +27,6 @@ function Checkout() {
         console.log('Payment failed:', result.error);
       }
     },
-    onExpressPayment: (result) => {
-      console.log('Express payment:', result);
-    },
   });
 
   return (
@@ -53,9 +52,6 @@ const payment = new FlintNPayment({
       console.log('Payment failed:', result.error);
     }
   },
-  onExpressPayment: (result) => {
-    console.log('Express payment:', result);
-  },
   onReady: () => {
     console.log('Widget ready');
   },
@@ -110,23 +106,22 @@ Do **not** set a fixed `height` on the container — it will leave empty space b
 
 | Option | Type | Required | Default | Description |
 |--------|------|----------|---------|-------------|
-| `clientSessionId` | `string` | ✅ | — | Client session ID from backend |
-| `formFields` | `FormFields` | ❌ | — | Form field visibility and requirements |
-| `styles` | `FormStyles` | ❌ | — | Custom styles for the checkout form |
-| `successRedirectUrl` | `string` | ❌ | — | Redirect URL after successful payment |
+| `config` | `FlintNConfig` | Yes | — | Checkout configuration |
+| `onPayment` | `(result: PaymentResult) => void` | No | — | Card payment result callback |
+| `onReady` | `() => void` | No | — | Widget loaded and ready |
+| `onError` | `(error: PaymentError) => void` | No | — | SDK initialization error |
+| `debug` | `boolean` | No | `false` | Enable console debug logs |
 
-> **Note:** `formFields` only applies when using Primer as the payment provider.
+### FlintNConfig
 
-## Callbacks
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `clientSessionId` | `string` | Yes | Client session ID from backend |
+| `formFields` | `FormFields` | No | Form field visibility and requirements |
+| `styles` | `FormStyles` | No | Custom styles for the checkout form |
+| `successRedirectUrl` | `string` | No | Redirect URL after successful payment |
 
-| Callback | Description |
-|----------|-------------|
-| `onPayment` | Fired when card payment completes (success or error) |
-| `onExpressPayment` | Fired when express payment completes (Apple Pay, Google Pay, PayPal) |
-| `onReady` | Fired when widget is loaded and ready |
-| `onError` | Fired on SDK initialization error |
-
-## React Hook Return Values
+### React Hook Return Values
 
 | Value | Type | Description |
 |-------|------|-------------|
@@ -135,7 +130,227 @@ Do **not** set a fixed `height` on the container — it will leave empty space b
 | `paymentResult` | `PaymentResult \| null` | Result after payment attempt |
 | `error` | `PaymentError \| null` | SDK error if any |
 
-## Types
+---
+
+## Hosted Fields
+
+Individual PCI-compliant input fields rendered as separate iframes. You control the layout, labels, and error display — the SDK handles card data securely.
+
+Each field (card number, expiry, CVV) is a separate iframe. Raw card data never touches your page.
+
+### React
+```tsx
+import { useState } from 'react';
+import { useFlintNFields } from 'flintn-checkout/react';
+
+function CheckoutForm() {
+  const [cardholderName, setCardholderName] = useState('');
+
+  const {
+    cardNumberRef,
+    expiryRef,
+    cvvRef,
+    isReady,
+    fieldErrors,
+    cardBrand,
+    paymentResult,
+    submit,
+    error,
+  } = useFlintNFields({
+    config: {
+      clientSessionId: 'your_client_session_id',
+      styles: {
+        inputBorderRadius: '8px',
+        inputBorderFocusColor: '#6366f1',
+      },
+    },
+    onPayment: (result) => {
+      if (result.status === 'PAYMENT_SUCCESS') {
+        console.log('Payment succeeded:', result.data);
+      }
+    },
+    debug: true,
+  });
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    const result = await submit({ cardholderName });
+    console.log('Payment result:', result);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <label>Card Number {cardBrand && `(${cardBrand})`}</label>
+      <div ref={cardNumberRef} style={{ height: 40, marginBottom: 4 }} />
+      {fieldErrors['card-number'] && (
+        <span style={{ color: 'red' }}>{fieldErrors['card-number']}</span>
+      )}
+
+      <div style={{ display: 'flex', gap: 12 }}>
+        <div style={{ flex: 1 }}>
+          <label>Expiry</label>
+          <div ref={expiryRef} style={{ height: 40, marginBottom: 4 }} />
+          {fieldErrors['expiry'] && (
+            <span style={{ color: 'red' }}>{fieldErrors['expiry']}</span>
+          )}
+        </div>
+        <div style={{ flex: 1 }}>
+          <label>CVV</label>
+          <div ref={cvvRef} style={{ height: 40, marginBottom: 4 }} />
+          {fieldErrors['cvv'] && (
+            <span style={{ color: 'red' }}>{fieldErrors['cvv']}</span>
+          )}
+        </div>
+      </div>
+
+      <label>Cardholder Name</label>
+      <input
+        value={cardholderName}
+        onChange={(e) => setCardholderName(e.target.value)}
+        placeholder="John Doe"
+      />
+
+      <button type="submit" disabled={!isReady}>
+        {isReady ? 'Pay' : 'Loading...'}
+      </button>
+
+      {error && <div style={{ color: 'red' }}>{error.message}</div>}
+      {paymentResult?.status === 'PAYMENT_ERROR' && paymentResult.error && (
+        <div style={{ color: 'red' }}>{paymentResult.error.message}</div>
+      )}
+    </form>
+  );
+}
+```
+
+### Vanilla JavaScript
+```javascript
+import { FlintNFields } from 'flintn-checkout';
+
+const fields = new FlintNFields({
+  config: {
+    clientSessionId: 'your_client_session_id',
+    styles: {
+      inputBorderRadius: '8px',
+      inputBorderFocusColor: '#6366f1',
+    },
+  },
+  onReady: () => console.log('All fields ready'),
+  onPayment: (result) => console.log('Payment result:', result),
+  onChange: (event) => console.log(`${event.fieldType}:`, event),
+  debug: true,
+});
+
+const cardNumber = fields.createField('card-number', { placeholder: '4111 1111 1111 1111' });
+const expiry = fields.createField('expiry', { placeholder: 'MM/YY' });
+const cvv = fields.createField('cvv', { placeholder: 'CVC' });
+
+cardNumber.mount('#card-number');
+expiry.mount('#expiry');
+cvv.mount('#cvv');
+
+// Validate
+const validation = await fields.validate();
+if (validation.isValid) {
+  const result = await fields.submit({ cardholderName: 'John Doe' });
+}
+
+// Cleanup
+fields.unmount();
+```
+
+### Hosted Fields Options (Vanilla JS)
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `config` | `FlintNFieldsConfig` | Yes | — | Fields configuration |
+| `onPayment` | `(result: PaymentResult) => void` | No | — | Payment result callback |
+| `onReady` | `() => void` | No | — | All fields loaded and ready |
+| `onChange` | `(event: FieldChangeEvent) => void` | No | — | Field value changed |
+| `onFocus` | `(fieldType: TFieldType) => void` | No | — | Field gained focus |
+| `onBlur` | `(fieldType: TFieldType, state: FieldState) => void` | No | — | Field lost focus |
+| `onError` | `(error: PaymentError) => void` | No | — | SDK initialization error |
+| `debug` | `boolean` | No | `false` | Enable console debug logs |
+
+### FlintNFieldsConfig
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `clientSessionId` | `string` | Yes | Client session ID from backend |
+| `styles` | `FormStyles` | No | Styles applied to all hosted field inputs |
+
+### React Hook Options
+
+The `useFlintNFields` hook accepts `config`, `onPayment`, and `debug` from the options above. It manages `onReady`, `onChange`, `onFocus`, `onBlur`, and `onError` internally and exposes them as return values instead.
+
+Additional React-only options:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `fields.cardNumber` | `FieldOptions \| false` | Card number field options, or `false` to skip |
+| `fields.expiry` | `FieldOptions \| false` | Expiry field options, or `false` to skip |
+| `fields.cvv` | `FieldOptions \| false` | CVV field options, or `false` to skip |
+| `onChange` | `(event: FieldChangeEvent) => void` | Optional additional callback |
+| `onFocus` | `(fieldType: TFieldType) => void` | Optional additional callback |
+| `onBlur` | `(fieldType: TFieldType, state: FieldState) => void` | Optional additional callback |
+
+### FieldOptions
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `placeholder` | `string` | Field-specific default | Input placeholder text |
+| `disabled` | `boolean` | `false` | Disable the input |
+
+### React Hook Return Values
+
+| Value | Type | Description |
+|-------|------|-------------|
+| `cardNumberRef` | `RefObject<HTMLDivElement>` | Ref for card number container |
+| `expiryRef` | `RefObject<HTMLDivElement>` | Ref for expiry container |
+| `cvvRef` | `RefObject<HTMLDivElement>` | Ref for CVV container |
+| `isReady` | `boolean` | All fields loaded and ready |
+| `fieldErrors` | `Partial<Record<TFieldType, string \| null>>` | Per-field validation errors (populated after first submit) |
+| `fieldStates` | `Partial<Record<TFieldType, FieldState>>` | Per-field state (always up to date) |
+| `cardBrand` | `string \| null` | Detected card brand (e.g. `"visa"`, `"mastercard"`) |
+| `paymentResult` | `PaymentResult \| null` | Result after payment attempt |
+| `error` | `PaymentError \| null` | SDK error if any |
+| `validate` | `() => Promise<FieldsValidationResult>` | Validate all fields |
+| `submit` | `(options?: SubmitOptions) => Promise<PaymentResult>` | Validate and submit payment |
+| `focusField` | `(fieldType: TFieldType) => void` | Focus a field programmatically |
+| `clearField` | `(fieldType: TFieldType) => void` | Clear a field |
+| `clearAll` | `() => void` | Clear all fields |
+
+### Validation Behavior
+
+Validation mirrors react-hook-form `mode: 'onSubmit'`:
+
+- Before first submit: `fieldErrors` is always `{}`
+- After first submit: errors update on every field change (revalidation)
+- Card number changes trigger CVV revalidation (CVV length depends on card brand)
+- All three fields (card number, expiry, CVV) are required — submitting with a missing field returns a `MISSING_FIELDS` error
+
+### Field Types
+
+| Value | Description |
+|-------|-------------|
+| `'card-number'` | Card number input with automatic formatting and brand detection |
+| `'expiry'` | Expiry date input (MM/YY format) |
+| `'cvv'` | CVV/CVC input (3 or 4 digits depending on card brand) |
+
+### Individual Field Methods (Vanilla JS)
+
+| Method | Description |
+|--------|-------------|
+| `field.mount(selector)` | Mount field into a DOM element |
+| `field.unmount()` | Remove field from DOM |
+| `field.focus()` | Focus the field |
+| `field.clear()` | Clear the field value |
+| `field.getState()` | Get current field state |
+| `field.getFieldType()` | Get the field type |
+
+---
+
+## Shared Types
 
 ### PaymentResult
 ```typescript
@@ -157,12 +372,42 @@ interface PaymentError {
 }
 ```
 
+### FieldState
+```typescript
+interface FieldState {
+  isEmpty: boolean;
+  isValid: boolean;
+  isFocused: boolean;
+  error: string | null;
+}
+```
+
+### FieldChangeEvent
+```typescript
+interface FieldChangeEvent {
+  fieldType: 'card-number' | 'expiry' | 'cvv';
+  isEmpty: boolean;
+  isValid: boolean;
+  isFocused: boolean;
+  error: string | null;
+  cardBrand?: string; // Only for card-number
+}
+```
+
+### FieldsValidationResult
+```typescript
+interface FieldsValidationResult {
+  isValid: boolean;
+  errors: Partial<Record<'card-number' | 'expiry' | 'cvv', string | null>>;
+}
+```
+
 ### FormFields
 ```typescript
 interface FormFields {
-  isEmailVisible?: boolean; // Primer only
+  isEmailVisible?: boolean;       // Primer only
   isCardholderNameRequired?: boolean; // Primer only
-  formVariant?: 'DEFAULT' | 'LIST';
+  formVariant?: 'DEFAULT' | 'LIST' | 'RADIO';
 }
 ```
 
@@ -191,52 +436,59 @@ interface FormStyles {
 
 ### FormStyles Reference
 
-| Property | Description |
-|----------|-------------|
-| `loaderColor` | Color of the loading spinner |
-| `backgroundColor` | Background color of the checkout form |
-| `expressButtonsSpacing` | Spacing between express payment buttons (Apple Pay, Google Pay, PayPal) |
-| `inputBackgroundColor` | Background color of input fields |
-| `inputBorderRadius` | Border radius of input fields |
-| `inputBorderColor` | Default border color of input fields |
-| `inputBorderHoverColor` | Border color of input fields on hover |
-| `inputBorderFocusColor` | Border color of input fields on focus |
-| `inputBorderErrorColor` | Border color of input fields in error state |
-| `errorMessageColor` | Color of error messages below inputs |
-| `buttonColor` | Background color of the submit button |
-| `buttonHoverColor` | Background color of the submit button on hover/active |
-| `buttonBorderRadius` | Border radius of the submit button |
-| `buttonText` | Custom text for the submit button (overrides default "Pay $X.XX") |
-| `cardButtonColor` | Background color of the "Credit or Debit Card" button (LIST variant only) |
-| `cardButtonHoverColor` | Hover/active color of the card button (LIST variant only) |
-| `cardButtonText` | Custom text for the card button (LIST variant only) |
+| Property | Iframe Checkout | Hosted Fields | Description |
+|----------|:-:|:-:|-------------|
+| `loaderColor` | ✅ | — | Loading spinner color |
+| `backgroundColor` | ✅ | — | Form background color |
+| `expressButtonsSpacing` | ✅ | — | Spacing between express payment buttons |
+| `inputBackgroundColor` | ✅ | ✅ | Input field background color |
+| `inputBorderRadius` | ✅ | ✅ | Input field border radius |
+| `inputBorderColor` | ✅ | ✅ | Default input border color |
+| `inputBorderHoverColor` | ✅ | ✅ | Input border color on hover |
+| `inputBorderFocusColor` | ✅ | ✅ | Input border color on focus |
+| `inputBorderErrorColor` | ✅ | ✅ | Input border color in error state |
+| `errorMessageColor` | ✅ | — | Error message text color |
+| `buttonColor` | ✅ | — | Submit button background color |
+| `buttonHoverColor` | ✅ | — | Submit button hover color |
+| `buttonBorderRadius` | ✅ | — | Submit button border radius |
+| `buttonText` | ✅ | — | Custom submit button text |
+| `cardButtonColor` | ✅ | — | Card button color (LIST variant) |
+| `cardButtonHoverColor` | ✅ | — | Card button hover color (LIST variant) |
+| `cardButtonText` | ✅ | — | Custom card button text (LIST variant) |
 
 ## Form Variants
 
-The checkout form supports two layout variants via `formFields.formVariant`:
+The iframe checkout supports three layout variants via `formFields.formVariant`:
 
-- **DEFAULT** — Express payment methods shown above the card form with dividers
-- **LIST** — Express payment methods shown as a list with a "Credit or Debit Card" button; clicking it navigates to the card form with a back arrow
+- **DEFAULT** — Express payment methods shown above the card form with dividers.
+- **LIST** — Express payment methods shown first; users tap a "Credit or Debit Card" button to navigate to the card form, with a back arrow to return to the express view.
+- **RADIO** — Express payments and the card form are presented as two radio options ("Fast checkout" and "Card payment"). Selecting a radio expands its section and collapses the other. The card payment radio shows accepted card brand logos inline with its label.
+
+LIST and RADIO automatically fall back to the DEFAULT layout when no express payment methods are available, since there's nothing to toggle between. The `cardButtonColor`, `cardButtonHoverColor`, and `cardButtonText` style overrides apply only to the LIST variant's "Credit or Debit Card" button.
 
 ## Supported Payment Methods
 
-- 💳 Credit/Debit Cards (Visa, Mastercard, Amex, Discover)
-- 🍎 Apple Pay
-- 🔵 Google Pay
-- 🟡 PayPal
+### Iframe Checkout
+- Credit/Debit Cards (Visa, Mastercard, Amex, Discover)
+- Apple Pay
+- Google Pay
+- PayPal
+
+### Hosted Fields
+- Credit/Debit Cards (Visa, Mastercard, Amex, Discover)
 
 ## Debug Mode
 
 Enable debug logs in console:
 ```typescript
-// React
+// Iframe Checkout
 useFlintNPayment({
   config: { clientSessionId: '...' },
   debug: true,
 });
 
-// Vanilla JS
-new FlintNPayment({
+// Hosted Fields
+useFlintNFields({
   config: { clientSessionId: '...' },
   debug: true,
 });

package/dist/index.d.mts

@@ -13,6 +13,7 @@ type TEventType = (typeof EventType)[keyof typeof EventType];
 declare const CheckoutFormVariant: {
     readonly DEFAULT: "DEFAULT";
     readonly LIST: "LIST";
+    readonly RADIO: "RADIO";
 };
 type TCheckoutFormVariant = (typeof CheckoutFormVariant)[keyof typeof CheckoutFormVariant];
 interface FormFields {
@@ -66,24 +67,109 @@ interface FlintNPaymentOptions {
     onError?: (error: PaymentError) => void;
     debug?: boolean;
 }
+declare const FieldType: {
+    readonly CARD_NUMBER: "card-number";
+    readonly EXPIRY: "expiry";
+    readonly CVV: "cvv";
+};
+type TFieldType = (typeof FieldType)[keyof typeof FieldType];
+declare const FieldEventType: {
+    readonly FIELD_CONFIG: "FIELD_CONFIG";
+    readonly FIELD_VALIDATE: "FIELD_VALIDATE";
+    readonly FIELD_SUBMIT: "FIELD_SUBMIT";
+    readonly FIELD_FOCUS_REQUEST: "FIELD_FOCUS_REQUEST";
+    readonly FIELD_CLEAR: "FIELD_CLEAR";
+    readonly FIELD_READY: "FIELD_READY";
+    readonly FIELD_CHANGE: "FIELD_CHANGE";
+    readonly FIELD_FOCUS: "FIELD_FOCUS";
+    readonly FIELD_BLUR: "FIELD_BLUR";
+    readonly FIELD_VALIDATION: "FIELD_VALIDATION";
+    readonly FIELD_SUBMIT_RESULT: "FIELD_SUBMIT_RESULT";
+    readonly FIELD_HEIGHT: "FIELD_HEIGHT";
+};
+type TFieldEventType = (typeof FieldEventType)[keyof typeof FieldEventType];
+interface FieldOptions {
+    placeholder?: string;
+    disabled?: boolean;
+}
+interface FieldState {
+    isEmpty: boolean;
+    isValid: boolean;
+    isFocused: boolean;
+    error: string | null;
+}
+interface FieldChangeEvent {
+    fieldType: TFieldType;
+    isEmpty: boolean;
+    isValid: boolean;
+    isFocused: boolean;
+    error: string | null;
+    cardBrand?: string;
+}
+interface FieldValidationResult {
+    fieldType: TFieldType;
+    isValid: boolean;
+    error: string | null;
+}
+interface FieldsValidationResult {
+    isValid: boolean;
+    errors: Partial<Record<TFieldType, string | null>>;
+}
+interface SubmitOptions {
+    cardholderName?: string;
+}
+interface FlintNFieldsConfig {
+    clientSessionId: string;
+    styles?: FormStyles;
+}
+interface FlintNFieldsOptions {
+    origin?: string;
+    config: FlintNFieldsConfig;
+    onPayment?: (result: PaymentResult) => void;
+    onReady?: () => void;
+    onChange?: (event: FieldChangeEvent) => void;
+    onFocus?: (fieldType: TFieldType) => void;
+    onBlur?: (fieldType: TFieldType, state: FieldState) => void;
+    onError?: (error: PaymentError) => void;
+    debug?: boolean;
+}
 
-declare class FlintNPayment {
-    private options;
-    private origin;
-    private iframe;
-    private container;
-    private isReady;
-    private messageHandler;
-    constructor(options: FlintNPaymentOptions);
+interface FlintNPayment {
     mount(selector: string | HTMLElement): void;
     unmount(): void;
     getIsReady(): boolean;
-    private handleMessage;
-    private isValidRedirectUrl;
-    private handlePaymentResult;
-    private sendConfig;
-    private log;
 }
+declare function createFlintNPayment(options: FlintNPaymentOptions): FlintNPayment;
+
+interface FlintNFieldInternalCallbacks {
+    onReady: (fieldType: TFieldType) => void;
+    onChange: (event: FieldChangeEvent) => void;
+    onFocus: (fieldType: TFieldType) => void;
+    onBlur: (fieldType: TFieldType, state: FieldState) => void;
+    onHeight: (fieldType: TFieldType, height: number) => void;
+}
+interface FlintNField {
+    mount(selector: string | HTMLElement): void;
+    unmount(): void;
+    focus(): void;
+    clear(): void;
+    getState(): FieldState;
+    getFieldType(): TFieldType;
+    _sendMessage(type: string, payload: unknown): void;
+    _getIframe(): HTMLIFrameElement | null;
+    _handleMessage(type: string, payload: Record<string, unknown>): void;
+}
+declare function createFlintNField(fieldType: TFieldType, origin: string, clientSessionId: string, options: FieldOptions, callbacks: FlintNFieldInternalCallbacks, debug?: boolean, formStyles?: FormStyles): FlintNField;
+
+interface FlintNFields {
+    createField(fieldType: TFieldType, options?: FieldOptions): FlintNField;
+    getField(fieldType: TFieldType): FlintNField | undefined;
+    validate(): Promise<FieldsValidationResult>;
+    submit(options?: SubmitOptions, skipValidation?: boolean): Promise<PaymentResult>;
+    unmount(): void;
+    getIsReady(): boolean;
+}
+declare function createFlintNFields(options: FlintNFieldsOptions): FlintNFields;
 
 declare const parseOrigin: (origin: string) => string;
 declare const buildIframeSrc: (origin: string) => string;
@@ -93,4 +179,4 @@ declare const validateConfig: (config: {
 }) => void;
 declare const sanitizeToken: (token: string) => string;
 
-export { CheckoutFormVariant, EventType, type FlintNConfig, FlintNPayment, type FlintNPaymentOptions, type FormFields, type FormStyles, type PaymentError, type PaymentResult, type TCheckoutFormVariant, type TEventType, buildIframeSrc, createIframeElement, parseOrigin, sanitizeToken, validateConfig };
+export { CheckoutFormVariant, EventType, type FieldChangeEvent, FieldEventType, type FieldOptions, type FieldState, FieldType, type FieldValidationResult, type FieldsValidationResult, type FlintNConfig, type FlintNField, type FlintNFieldInternalCallbacks, type FlintNFields, type FlintNFieldsConfig, type FlintNFieldsOptions, type FlintNPayment, type FlintNPaymentOptions, type FormFields, type FormStyles, type PaymentError, type PaymentResult, type SubmitOptions, type TCheckoutFormVariant, type TEventType, type TFieldEventType, type TFieldType, buildIframeSrc, createFlintNField, createFlintNFields, createFlintNPayment, createIframeElement, parseOrigin, sanitizeToken, validateConfig };