# Rebill Web Components SDK (v3.1)

> A framework‑agnostic Web Components SDK (built with Stencil) to embed Rebill checkout, payments, and renewal flows in any website or app.

This SDK provides production‑ready components (checkout form, payment method selector, card iframe, OTP, discounts, summary, renewal), **dynamic runtime configuration**, i18n support, and a lightweight loader for easy integration.

## 🚀 Quick Start

### Prerequisites

- **Node.js**: >= 16.0.0
- **pnpm**: >= 8.0.0 (required)

Install pnpm globally if you haven't already:

```bash
npm install -g pnpm
```

### 1. Install the SDK

```bash
pnpm install rebill
```

### 2. Use Components (No initialization required!)

```html
<!-- Your HTML - works out of the box with production settings -->
<rebill-checkout></rebill-checkout>
```

## 📘 TypeScript / JSX Support

**TypeScript support is now automatic!** 🎉

If you were experiencing this error:

```
Property 'rebill-checkout' does not exist on type 'JSX.IntrinsicElements'.
```

Just update to the latest version and import from the SDK:

```typescript
import { initializeRebillSDK } from 'rebill/config';
// or
import { defineCustomElements } from 'rebill/loader';
```

The JSX types will load automatically. **No `tsconfig.json` configuration needed!**

```typescript
// Or programmatically
import { defineCustomElements } from 'rebill/loader';
defineCustomElements(window);
```

### 3. Optional: Configure for Different Environments

```typescript
import { initializeRebillSDK } from 'rebill';

// Only needed if you want to use staging or development
initializeRebillSDK({
  environment: 'staging', // 'development' | 'staging' | 'production'
  debug: true,
});
```

## 🔧 Configuration

The SDK works **out of the box** with production settings. Configuration is **optional** and only needed for staging or development environments.

### Default Behavior

- **Production environment** by default
- **No initialization required** for client applications
- **Production API endpoints** automatically used

### Optional Environment Configuration

```typescript
import { initializeRebillSDK } from 'rebill';

// For staging with CDN assets (optional)
initializeRebillSDK({
  environment: 'staging',
  debug: true,
});

// For staging with local assets
initializeRebillSDK({
  environment: 'staging',
  debug: true,
  assetsUrl: '/sdk/', // Serve assets from local path
});

// For development (optional)
initializeRebillSDK({
  environment: 'development',
  debug: true,
});

// For production (optional - this is the default)
initializeRebillSDK({
  environment: 'production',
  debug: false,
});
```

### Quick Helpers

```typescript
import { RebillSDK } from 'rebill';

// Quick setup (all optional)
RebillSDK.forProduction(); // Default behavior
RebillSDK.forStaging(); // For testing
RebillSDK.forDevelopment(); // For local development
```

## 🚀 Assets Configuration (CDN vs Local)

**By default, assets are loaded automatically from CDN. No configuration needed.**

The SDK automatically uses `https://unpkg.com/rebill@[version]/assets/` to load icons and animations.

### Basic Usage (CDN - No Configuration)

```typescript
import { initializeRebillSDK } from 'rebill';
import { defineCustomElements } from 'rebill/loader';

// Assets load automatically from CDN
initializeRebillSDK({
  environment: 'staging',
  debug: true,
});

defineCustomElements(window);
```

### Using Local Assets

#### Option 1: Configure via initializeRebillSDK (Recommended)

```typescript
import { initializeRebillSDK } from 'rebill';
import { defineCustomElements } from 'rebill/loader';

// Configure local assets
initializeRebillSDK({
  environment: 'staging',
  debug: true,
  assetsUrl: '/sdk/', // Use local assets from /sdk/ path
});

defineCustomElements(window);
```

**Important:** When using `assetsUrl`, you must ensure the assets are available at that path. Copy the `assets` folder from `node_modules/rebill/dist/assets/` to your public folder.

#### Option 2: Using setAssetsURL (Alternative)

```typescript
import { defineCustomElements } from 'rebill/loader';
import { setAssetsURL } from 'rebill';

// Configure assets before defining elements
setAssetsURL('/sdk/');
defineCustomElements(window);
```

### Complete Example - React with Local Assets

```typescript
import { useEffect } from 'react';
import { initializeRebillSDK } from 'rebill';
import { defineCustomElements } from 'rebill/loader';

export function useRebillSDK() {
  useEffect(() => {
    const environment = process.env.NEXT_PUBLIC_NODE_ENV as
      | 'development'
      | 'staging'
      | 'production';

    if (environment === 'development' || environment === 'staging') {
      // Use local assets in development/staging
      initializeRebillSDK({
        environment: 'staging',
        debug: true,
        assetsUrl: '/sdk/', // Serve from /public/sdk/ folder
      });
    } else {
      // Use CDN in production
      initializeRebillSDK({
        environment: 'production',
        debug: false,
      });
    }

    defineCustomElements(window);
  }, []);
}
```

### CDN Benefits

- ✅ **Zero configuration** - Works immediately
- ✅ **Global cache** - Faster asset loading
- ✅ **Automatic versioning** - Always uses the correct version
- ✅ **No manual copies** - No need to copy files
- ✅ **Flexible** - Can override URL when needed

### Local Assets Benefits

- ✅ **Full control** - Assets served from your domain
- ✅ **Offline support** - Works without external CDN
- ✅ **Custom builds** - Can modify assets if needed
- ✅ **Privacy** - No external requests
