@payment-kit-js/vanilla 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,755 @@
+# @payment-kit-js/vanilla
+
+Vanilla JavaScript SDK for PaymentKit - A type-safe, framework-agnostic payment processing SDK supporting card payments, PayPal, and Google Pay.
+
+## Installation
+
+```bash
+npm install @payment-kit-js/vanilla
+```
+
+## Quick Start
+
+```typescript
+import PaymentKit from '@payment-kit-js/vanilla';
+import CardPaymentMethod from '@payment-kit-js/vanilla/payment-methods/card';
+
+// Initialize PaymentKit
+const paymentKit = PaymentKit({
+  baseUrl: 'https://your-domain.com',      // For loading iframes
+  apiBaseUrl: 'https://api.domain.com',    // For API calls (optional, defaults to baseUrl)
+  secureToken: 'checkout_session_token',   // From your backend
+  paymentMethods: [CardPaymentMethod]
+});
+
+// Mount card inputs
+paymentKit.card.createElement('card_pan').mount('#card-number');
+paymentKit.card.createElement('card_exp').mount('#card-expiry');
+paymentKit.card.createElement('card_cvc').mount('#card-cvc');
+
+// Submit payment
+paymentKit.submit({
+  fields: {
+    customer_name: 'John Doe',
+    customer_email: 'john@example.com',
+    customer_country: 'US',
+    customer_zip_code: '10001'
+  },
+  paymentMethod: 'card',
+  onSuccess: (result) => console.log('Success:', result),
+  onError: (errors) => console.error('Error:', errors)
+});
+
+// Cleanup when done
+paymentKit.cleanup();
+```
+
+## Payment Methods
+
+### Card Payments
+
+Secure PCI-compliant card payments using isolated iframes.
+
+#### Import
+
+```typescript
+import CardPaymentMethod from '@payment-kit-js/vanilla/payment-methods/card';
+import type { CardInputType } from '@payment-kit-js/vanilla/payment-methods/card';
+```
+
+#### Initialize
+
+```typescript
+const paymentKit = PaymentKit({
+  baseUrl: 'https://your-domain.com',
+  secureToken: 'checkout_token',
+  paymentMethods: [CardPaymentMethod]
+});
+```
+
+#### Create Card Elements
+
+```typescript
+// Card input types: 'card_pan' | 'card_exp' | 'card_cvc'
+const cardNumber = paymentKit.card.createElement('card_pan', {
+  style: {
+    height: '40px',
+    fontSize: '16px',
+    fontFamily: 'Arial, sans-serif',
+    color: '#32325d',
+    padding: '10px'
+  },
+  onLoaded: () => console.log('Card input loaded'),
+  onFocusChange: (isFocused) => console.log('Focus:', isFocused)
+});
+
+// Mount to DOM
+const { unmount } = cardNumber.mount('#card-number-container');
+
+// Unmount when needed
+unmount();
+```
+
+#### Submit Card Payment
+
+```typescript
+paymentKit.submit({
+  fields: {
+    customer_name: 'John Doe',
+    customer_email: 'john@example.com',
+    customer_country: 'US',
+    customer_zip_code: '10001'
+  },
+  paymentMethod: 'card',
+  onSuccess: (result) => {
+    // result: { id, checkoutAttemptId, checkoutSessionId, paymentIntentId, state }
+    console.log('Payment successful:', result);
+  },
+  onError: (errors) => {
+    // errors.card_pan, errors.card_exp, errors.card_cvc
+    // errors.customer_name, errors.customer_email, etc.
+    console.error('Payment failed:', errors);
+  }
+});
+```
+
+#### 3D Secure (3DS) Support
+
+Card payments automatically handle 3D Secure authentication:
+
+1. Submit payment
+2. If 3DS required, user is redirected to bank authentication page
+3. After authentication, payment completes automatically
+4. Success/error callback is triggered
+
+No additional code needed - it's built-in!
+
+### PayPal
+
+PayPal payments using popup-based authentication flow.
+
+#### Import
+
+```typescript
+import PayPalPaymentMethod from '@payment-kit-js/vanilla/payment-methods/paypal';
+import type { PayPalSubmitOptions } from '@payment-kit-js/vanilla/payment-methods/paypal';
+```
+
+#### Initialize
+
+```typescript
+const paymentKit = PaymentKit({
+  baseUrl: 'https://your-domain.com',
+  apiBaseUrl: 'https://api.domain.com',
+  secureToken: 'checkout_token',
+  paymentMethods: [PayPalPaymentMethod]
+});
+```
+
+#### Submit PayPal Payment
+
+```typescript
+paymentKit.submit({
+  fields: {
+    customer_name: 'John Doe',
+    customer_email: 'john@example.com',
+    customer_country: 'US',
+    customer_zip_code: '10001'
+  },
+  paymentMethod: 'paypal',
+  options: {
+    processorId: 'proc_xxx',  // Your PayPal processor ID
+    customerInfo: {
+      first_name: 'John',
+      last_name: 'Doe'
+    }
+  },
+  onSuccess: (result) => {
+    console.log('PayPal payment approved:', result);
+  },
+  onError: (errors) => {
+    if (errors.paypal?.includes('popup')) {
+      alert('Please allow popups for PayPal payments');
+    }
+    console.error('PayPal error:', errors);
+  }
+});
+```
+
+**Important**: PayPal requires browser popups to be enabled. The SDK automatically:
+- Opens PayPal authentication popup
+- Polls for payment completion every 2 seconds
+- Closes popup after completion
+- Handles user cancellation
+
+### Google Pay
+
+Google Pay payments using Stripe Payment Request API.
+
+#### Import
+
+```typescript
+import GooglePayPaymentMethod from '@payment-kit-js/vanilla/payment-methods/google-pay';
+import type { GooglePaySubmitOptions } from '@payment-kit-js/vanilla/payment-methods/google-pay';
+```
+
+#### Prerequisites
+
+Add Stripe.js to your HTML:
+
+```html
+<script src="https://js.stripe.com/v3/"></script>
+```
+
+#### Initialize
+
+```typescript
+const paymentKit = PaymentKit({
+  baseUrl: 'https://your-domain.com',
+  apiBaseUrl: 'https://api.domain.com',
+  secureToken: 'checkout_token',
+  paymentMethods: [GooglePayPaymentMethod]
+});
+```
+
+#### Submit Google Pay Payment
+
+```typescript
+paymentKit.submit({
+  fields: {
+    customer_name: 'John Doe',
+    customer_email: 'john@example.com',
+    customer_country: 'US',
+    customer_zip_code: '10001'
+  },
+  paymentMethod: 'google_pay',
+  options: {
+    processorId: 'proc_xxx',  // Your Google Pay processor ID
+    customerInfo: {
+      first_name: 'John',
+      last_name: 'Doe'
+    }
+  },
+  onSuccess: (result) => {
+    console.log('Google Pay success:', result);
+  },
+  onError: (errors) => {
+    if (errors.google_pay === 'Google Pay not available on this device') {
+      // Show alternative payment methods
+    }
+    console.error('Google Pay error:', errors);
+  }
+});
+```
+
+## Multiple Payment Methods
+
+Enable multiple payment methods in a single instance:
+
+```typescript
+import CardPaymentMethod from '@payment-kit-js/vanilla/payment-methods/card';
+import PayPalPaymentMethod from '@payment-kit-js/vanilla/payment-methods/paypal';
+import GooglePayPaymentMethod from '@payment-kit-js/vanilla/payment-methods/google-pay';
+
+const paymentKit = PaymentKit({
+  baseUrl: 'https://your-domain.com',
+  apiBaseUrl: 'https://api.domain.com',
+  secureToken: 'checkout_token',
+  paymentMethods: [CardPaymentMethod, PayPalPaymentMethod, GooglePayPaymentMethod]
+});
+
+// TypeScript knows all available methods
+paymentKit.card.createElement('card_pan');  // ✓
+paymentKit.submit({ paymentMethod: 'card', ... });      // ✓
+paymentKit.submit({ paymentMethod: 'paypal', ... });    // ✓
+paymentKit.submit({ paymentMethod: 'google_pay', ... }); // ✓
+```
+
+## API Reference
+
+### `PaymentKit(config)`
+
+Initialize PaymentKit instance.
+
+**Parameters**:
+
+```typescript
+{
+  baseUrl: string;              // URL for loading iframes (e.g., https://your-domain.com)
+  apiBaseUrl?: string;          // URL for API calls (defaults to baseUrl)
+  secureToken: string;          // Checkout session token from your backend
+  paymentMethods: PaymentMethod[];  // Array of payment method handlers
+}
+```
+
+**Returns**: Object with payment method APIs + `submit()` + `cleanup()`
+
+### `submit(options)`
+
+Submit a payment using specified payment method.
+
+**Parameters**:
+
+```typescript
+{
+  fields: {
+    customer_name: string;
+    customer_email: string;
+    customer_country: string;
+    customer_zip_code: string;
+  };
+  paymentMethod: 'card' | 'paypal' | 'google_pay';
+  options?: unknown;  // Payment method specific options
+  onSuccess: (result: { [key: string]: unknown }) => void;
+  onError: (errors: PaymentKitErrors) => void;
+}
+```
+
+### `cleanup()`
+
+Clean up all resources (iframes, popups, connections). **Always call this** when unmounting or leaving checkout.
+
+```typescript
+useEffect(() => {
+  return () => {
+    paymentKit.cleanup();
+  };
+}, [paymentKit]);
+```
+
+### Card API
+
+#### `card.createElement(type, options)`
+
+Create a secure card input iframe.
+
+**Types**:
+- `'card_pan'` - Card number
+- `'card_exp'` - Expiration (MM/YY)
+- `'card_cvc'` - Security code
+
+**Options**:
+
+```typescript
+{
+  style?: Record<string, string>;  // CSS properties
+  onLoaded?: () => void;
+  onFocusChange?: (isFocused: boolean) => void;
+}
+```
+
+**Returns**: `{ mount: (selector: string) => { unmount: () => void } }`
+
+## Types
+
+### PaymentKitFields
+
+```typescript
+type PaymentKitFields = {
+  customer_name: string;
+  customer_email: string;
+  customer_country: string;
+  customer_zip_code: string;
+};
+```
+
+### PaymentKitErrors
+
+```typescript
+type PaymentKitErrors = {
+  root?: string;
+
+  // Card errors
+  card_pan?: CardErrorCode;
+  card_exp?: CardErrorCode;
+  card_cvc?: CardErrorCode;
+
+  // PayPal errors
+  paypal?: string;
+
+  // Google Pay errors
+  google_pay?: string;
+
+  // Field validation
+  customer_name?: 'required' | 'invalid';
+  customer_email?: 'required' | 'invalid';
+  customer_country?: 'required' | 'invalid';
+  customer_zip_code?: 'required' | 'invalid';
+
+  // Processor
+  processor_id?: string;
+};
+```
+
+### CardErrorCode
+
+```typescript
+type CardErrorCode =
+  | 'required'
+  | 'invalid'
+  | 'incomplete'
+  | 'invalid_number'
+  | 'invalid_expiry'
+  | 'invalid_cvc';
+```
+
+## React Example
+
+### PaymentKit Provider
+
+```tsx
+import { createContext, useContext, useEffect, useState } from 'react';
+import PaymentKit from '@payment-kit-js/vanilla';
+import CardPaymentMethod from '@payment-kit-js/vanilla/payment-methods/card';
+import PayPalPaymentMethod from '@payment-kit-js/vanilla/payment-methods/paypal';
+import GooglePayPaymentMethod from '@payment-kit-js/vanilla/payment-methods/google-pay';
+
+type PaymentKitInstance = ReturnType<typeof PaymentKit<
+  [typeof CardPaymentMethod, typeof PayPalPaymentMethod, typeof GooglePayPaymentMethod]
+>>;
+
+const PaymentKitContext = createContext<PaymentKitInstance | null>(null);
+
+export const usePaymentKit = () => {
+  const pk = useContext(PaymentKitContext);
+  if (!pk) throw new Error('PaymentKit not initialized');
+  return pk;
+};
+
+export const PaymentKitProvider = ({
+  children,
+  secureToken
+}: {
+  children: React.ReactNode;
+  secureToken: string;
+}) => {
+  const [paymentKit, setPaymentKit] = useState<PaymentKitInstance | null>(null);
+
+  useEffect(() => {
+    const pk = PaymentKit({
+      baseUrl: 'https://your-domain.com',
+      apiBaseUrl: 'https://api.domain.com',
+      secureToken,
+      paymentMethods: [CardPaymentMethod, PayPalPaymentMethod, GooglePayPaymentMethod]
+    });
+
+    setPaymentKit(pk);
+    return () => pk.cleanup();
+  }, [secureToken]);
+
+  if (!paymentKit) return null;
+
+  return (
+    <PaymentKitContext.Provider value={paymentKit}>
+      {children}
+    </PaymentKitContext.Provider>
+  );
+};
+```
+
+### Card Input Component
+
+```tsx
+import { useEffect } from 'react';
+import { usePaymentKit } from './PaymentKitProvider';
+import type { CardInputType } from '@payment-kit-js/vanilla/payment-methods/card';
+
+export const CardInput = ({
+  type,
+  className
+}: {
+  type: CardInputType;
+  className?: string;
+}) => {
+  const paymentKit = usePaymentKit();
+
+  useEffect(() => {
+    const element = paymentKit.card.createElement(type, {
+      style: {
+        height: '42px',
+        fontSize: '16px',
+        padding: '10px',
+        border: '1px solid #e0e0e0',
+        borderRadius: '4px'
+      }
+    });
+
+    const { unmount } = element.mount(`#${type}`);
+    return unmount;
+  }, [type, paymentKit]);
+
+  return <div id={type} className={className} />;
+};
+```
+
+### Payment Form
+
+```tsx
+import { useState } from 'react';
+import { usePaymentKit } from './PaymentKitProvider';
+import { CardInput } from './CardInput';
+
+export const PaymentForm = () => {
+  const paymentKit = usePaymentKit();
+  const [loading, setLoading] = useState(false);
+  const [values, setValues] = useState({
+    customer_name: '',
+    customer_email: '',
+    customer_country: '',
+    customer_zip_code: ''
+  });
+
+  const handleCardPayment = () => {
+    setLoading(true);
+    paymentKit.submit({
+      fields: values,
+      paymentMethod: 'card',
+      onSuccess: (result) => {
+        setLoading(false);
+        console.log('Success:', result);
+      },
+      onError: (errors) => {
+        setLoading(false);
+        console.error('Error:', errors);
+      }
+    });
+  };
+
+  const handlePayPalPayment = () => {
+    const [firstName, ...rest] = values.customer_name.split(' ');
+    setLoading(true);
+
+    paymentKit.submit({
+      fields: values,
+      paymentMethod: 'paypal',
+      options: {
+        processorId: 'proc_xxx',
+        customerInfo: {
+          first_name: firstName,
+          last_name: rest.join(' ')
+        }
+      },
+      onSuccess: (result) => {
+        setLoading(false);
+        console.log('PayPal success:', result);
+      },
+      onError: (errors) => {
+        setLoading(false);
+        console.error('PayPal error:', errors);
+      }
+    });
+  };
+
+  const handleGooglePayment = () => {
+    const [firstName, ...rest] = values.customer_name.split(' ');
+    setLoading(true);
+
+    paymentKit.submit({
+      fields: values,
+      paymentMethod: 'google_pay',
+      options: {
+        processorId: 'proc_xxx',
+        customerInfo: {
+          first_name: firstName,
+          last_name: rest.join(' ')
+        }
+      },
+      onSuccess: (result) => {
+        setLoading(false);
+        console.log('Google Pay success:', result);
+      },
+      onError: (errors) => {
+        setLoading(false);
+        console.error('Google Pay error:', errors);
+      }
+    });
+  };
+
+  return (
+    <form onSubmit={(e) => e.preventDefault()}>
+      <input
+        placeholder="Name"
+        value={values.customer_name}
+        onChange={(e) => setValues(prev => ({ ...prev, customer_name: e.target.value }))}
+      />
+      <input
+        placeholder="Email"
+        value={values.customer_email}
+        onChange={(e) => setValues(prev => ({ ...prev, customer_email: e.target.value }))}
+      />
+      <input
+        placeholder="Country"
+        value={values.customer_country}
+        onChange={(e) => setValues(prev => ({ ...prev, customer_country: e.target.value }))}
+      />
+      <input
+        placeholder="Zip Code"
+        value={values.customer_zip_code}
+        onChange={(e) => setValues(prev => ({ ...prev, customer_zip_code: e.target.value }))}
+      />
+
+      <h3>Card Payment</h3>
+      <CardInput type="card_pan" />
+      <CardInput type="card_exp" />
+      <CardInput type="card_cvc" />
+      <button onClick={handleCardPayment} disabled={loading}>
+        Pay with Card
+      </button>
+
+      <h3>Alternative Payments</h3>
+      <button onClick={handlePayPalPayment} disabled={loading}>
+        Pay with PayPal
+      </button>
+      <button onClick={handleGooglePayment} disabled={loading}>
+        Pay with Google Pay
+      </button>
+    </form>
+  );
+};
+```
+
+## Error Handling
+
+### Validation Errors
+
+```typescript
+paymentKit.submit({
+  fields: values,
+  paymentMethod: 'card',
+  onError: (errors) => {
+    if (errors.customer_email === 'required') {
+      showError('Email is required');
+    }
+    if (errors.card_pan === 'invalid_number') {
+      showError('Invalid card number');
+    }
+  },
+  onSuccess: () => { /* ... */ }
+});
+```
+
+### Payment Method Specific Errors
+
+```typescript
+// Card errors
+onError: (errors) => {
+  if (errors.card_pan) console.error('Card number error');
+  if (errors.card_exp) console.error('Expiry error');
+  if (errors.card_cvc) console.error('CVC error');
+}
+
+// PayPal errors
+onError: (errors) => {
+  if (errors.paypal?.includes('popup')) {
+    alert('Please enable popups');
+  }
+  if (errors.paypal?.includes('cancelled')) {
+    console.log('User cancelled PayPal');
+  }
+}
+
+// Google Pay errors
+onError: (errors) => {
+  if (errors.google_pay === 'Google Pay not available on this device') {
+    // Hide Google Pay button
+  }
+  if (errors.google_pay?.includes('cancelled')) {
+    console.log('User cancelled Google Pay');
+  }
+}
+```
+
+## Best Practices
+
+### 1. Always Cleanup
+
+```typescript
+useEffect(() => {
+  const pk = PaymentKit({ /* config */ });
+  return () => pk.cleanup(); // Critical!
+}, []);
+```
+
+### 2. Handle Loading States
+
+```typescript
+const [loading, setLoading] = useState(false);
+
+const handleSubmit = () => {
+  setLoading(true);
+  paymentKit.submit({
+    // ...
+    onSuccess: () => setLoading(false),
+    onError: () => setLoading(false)
+  });
+};
+```
+
+### 3. Validate Before Submit
+
+```typescript
+const handleSubmit = () => {
+  if (!values.customer_email || !values.customer_name) {
+    setError('Please fill required fields');
+    return;
+  }
+  paymentKit.submit({ /* ... */ });
+};
+```
+
+### 4. Provide Fallback for Unsupported Methods
+
+```typescript
+// Check Google Pay availability
+paymentKit.submit({
+  paymentMethod: 'google_pay',
+  onError: (errors) => {
+    if (errors.google_pay?.includes('not available')) {
+      setShowGooglePay(false); // Hide button
+    }
+  }
+});
+```
+
+### 5. Type Safety with TypeScript
+
+```typescript
+// Type the instance based on enabled payment methods
+type PaymentKitInstance = ReturnType<typeof PaymentKit<
+  [typeof CardPaymentMethod, typeof PayPalPaymentMethod]
+>>;
+
+// TypeScript enforces correct payment method names
+paymentKit.submit({ paymentMethod: 'card' }); // ✓
+paymentKit.submit({ paymentMethod: 'stripe' }); // ✗ Type error
+```
+
+## Troubleshooting
+
+### Card inputs not showing
+
+- Ensure DOM elements exist before mounting
+- Check `baseUrl` is accessible
+- Verify `secureToken` is valid
+
+### PayPal popup blocked
+
+- Instruct users to allow popups
+- Check browser console for errors
+- Verify `apiBaseUrl` is correct
+
+### Google Pay not available
+
+- Add Stripe.js script tag
+- Test on supported devices (Android Chrome, Safari on iOS)
+- Check `processorId` is valid
+
+### TypeScript errors
+
+- Ensure proper typing of PaymentKit instance
+- Import types from correct paths
+- Use `ReturnType<typeof PaymentKit<[...]>>` pattern
+
+## License
+
+MIT