# Cloudbeds Payment Element Web Component

A web component wrapper for the Cloudbeds Payment SDK, enabling easy integration of payment processing into any website or application. This package provides both CDN and NPM distribution methods for maximum flexibility.

## Features

- 🚀 **Easy Integration**: Drop-in web component that works with any framework
- 💳 **Multiple Payment Methods**: Credit cards, PayPal, Apple Pay, Google Pay, OXXO, and more
- 🌐 **Universal Compatibility**: Works with vanilla HTML, React, Vue, Angular, etc.
- 🎨 **Customizable**: Full theming support and customizable styling
- 🔒 **PCI Compliant**: Secure tokenization with industry-standard security
- 📱 **Responsive**: Mobile-friendly design that adapts to any screen size
- 🌍 **Internationalization**: Multi-language support

## Installation

### Via NPM (Recommended for bundled projects)

```bash
npm install @cloudbeds/payment-element-webcomponent
```

### Via CDN (For direct HTML usage)

```html
<script src="https://cdn.jsdelivr.net/npm/@cloudbeds/payment-element-webcomponent/cloudbeds-payment-element.min.js"></script>
```

## Quick Start

### CDN Usage

```html
<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/@cloudbeds/payment-element-webcomponent/cloudbeds-payment-element.min.js"></script>
</head>
<body>
  <payment-element-webcomponent
    api-key="YOUR_API_KEY"
    property-id="YOUR_PROPERTY_ID"
    amount="100.00"
    currency="USD"
    env="prod"
  ></payment-element-webcomponent>
  
  <button id="submit-btn">Submit Payment</button>
  
  <script>
    let paymentHandles = null;
    const paymentElement = document.querySelector('payment-element-webcomponent');
    
    // Get handles for submit and validate functions
    paymentElement['on-render'] = (handles) => {
      paymentHandles = handles;
    };
    
    // Submit payment
    document.getElementById('submit-btn').addEventListener('click', async () => {
      if (!paymentHandles) return;
      
      const isValid = await paymentHandles.validate();
      if (!isValid) {
        alert('Please complete all required fields');
        return;
      }
      
      const result = await paymentHandles.submit();
      console.log('Payment hash:', result?.paymentData?.paymentMethodHash);
    });
  </script>
</body>
</html>
```

### NPM Module Usage

#### ES Modules (Import)

```javascript
import { PaymentElementWebComponent } from '@cloudbeds/payment-element-webcomponent';

// Register the web component
customElements.define('my-payment-form', PaymentElementWebComponent);
```

#### CommonJS (Require)

```javascript
const { PaymentElementWebComponent } = require('@cloudbeds/payment-element-webcomponent');

// Register the web component
customElements.define('my-payment-form', PaymentElementWebComponent);
```

#### TypeScript

```typescript
import { PaymentElementWebComponent, PaymentHandles } from '@cloudbeds/payment-element-webcomponent';

// Register the web component
customElements.define('my-payment-form', PaymentElementWebComponent);

// Type-safe event handling
const paymentElement = document.querySelector('my-payment-form') as PaymentElementWebComponent;
paymentElement['on-render'] = (handles: PaymentHandles) => {
  // handles.submit() and handles.validate() are properly typed
};
```

## API Reference

### Attributes

| Attribute | Type | Required | Description |
|-----------|------|----------|-------------|
| `api-key` | string | ✅ | Your Cloudbeds API key |
| `property-id` | string | ✅ | Your property ID |
| `amount` | string | | Payment amount (e.g., "100.00") |
| `currency` | string | | Currency code (e.g., "USD", "EUR") |
| `env` | string | | Environment: "prod", "stage", "dev", or "local" |
| `lang` | string | | Language code for localization (e.g., "en", "es") |
| `guest` | string | | Guest information as JSON string |
| `theme` | string | | Custom theme configuration as JSON string |
| `allowed-payment-methods` | string | | Allowed payment methods as JSON array |
| `scoped-css` | string | | Enable scoped CSS ("true" or "false") |
| `capture` | string | | Payment capture mode ("auto" or "manual") |

### Event Handlers

| Event | Description | Callback Data |
|-------|-------------|---------------|
| `on-render` | Fired when component renders | `PaymentHandles` object |
| `on-load-start` | Fired when loading begins | None |
| `on-load-end` | Fired when loading completes | None |
| `on-change` | Fired when form data changes | Form data object |
| `on-error` | Fired when an error occurs | Error object |
| `on-submit` | Fired after payment submission | Submission result |

### PaymentHandles Methods

```typescript
interface PaymentHandles {
  submit(): Promise<PaymentResult>;
  validate(): Promise<boolean>;
}
```

## Complete Example

See the included `example.html` file for a comprehensive example showing:
- Multiple payment methods
- Event handling
- Validation
- Error handling
- Success handling

## Framework Integration

This web component works seamlessly with any JavaScript framework:

- **Vanilla HTML/JS**: Use directly with script tags
- **React**: For React-specific components, see [@cloudbeds/payment-sdk](https://www.npmjs.com/package/@cloudbeds/payment-sdk)
- **Vue.js**: Compatible with Vue 2 and Vue 3
- **Angular**: Works with any Angular version
- **Other frameworks**: Compatible with Svelte, Lit, and other modern frameworks

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Mobile browsers (iOS Safari, Chrome Mobile)

## Development

This package is part of the Cloudbeds Payment SDK monorepo. For development instructions, see the main repository.

## License

ISC License - see LICENSE file for details.

## Support

For issues and questions, please visit: https://github.com/cloudbeds/payment-sdk-workspaces/issues