npm package: @rudiq/payment-widget
Description: Rudiq Payment Widget - Web3 payment component built with Wagmi and Reown AppKit
Author: rudiq
Latest version: 1.0.3

# @apex/payment-widget

Web3 payment widget component built with Wagmi, Reown AppKit, and Viem. A simple, ready-to-use React component for accepting crypto payments.

## Installation

### Production Installation

```bash
npm install @apex/payment-widget
```

### Local Development (Testing Before Deployment)

To test the widget in your local project before deploying, you can use one of two methods:

#### Method 1: npm link (Recommended)

1. Create a link in the widget directory:
```bash
cd /path/to/apex-payment-widget
npm run build
npm link
```

2. Use the link in your project:
```bash
cd /path/to/your-project
npm link @rudiq/payment-widget
```

3. Usage:
```tsx
import { RudiqPaymentWidget } from '@rudiq/payment-widget'
```

4. When you make changes, rebuild in the widget directory:
```bash
cd /path/to/apex-payment-widget
npm run build
# or for watch mode:
npm run dev
```

5. To remove the link:
```bash
cd /path/to/your-project
npm unlink @rudiq/payment-widget
```

#### Method 2: Local Path (Alternative)

Specify the path directly in your package.json:

```json
{
  "dependencies": {
    "@rudiq/payment-widget": "file:../apex-payment-widget"
  }
}
```

Then:
```bash
npm install
```

## Quick Start

### React

```tsx
import { RudiqPaymentWidget } from '@rudiq/payment-widget'
import { useState } from 'react'

function App() {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open Payment Widget</button>
      <RudiqPaymentWidget
        host="https://api.example.com"
        paymentId="your-payment-id"
        token="your-bearer-token"
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
      />
    </>
  )
}
```

### Vue

```vue
<template>
  <div>
    <button @click="isOpen = true">Open Payment Widget</button>
    <RudiqPaymentWidget
      host="https://api.example.com"
      :paymentId="'your-payment-id'"
      :token="'your-bearer-token'"
      :isOpen="isOpen"
      @close="isOpen = false"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import RudiqPaymentWidget from '@rudiq/payment-widget/vue'

const isOpen = ref(false)
</script>
```

## Props

### RudiqPaymentWidget

- `host` (string, required): Base URL for the payment widget (e.g., `"https://api.example.com"`)
- `paymentId` (string, required): Payment ID for the payment
- `token` (string, required): Bearer token for API authentication
- `isOpen` (boolean, required): Controls the visibility of the widget modal
- `onClose` (function, required): Callback function called when the widget is closed
- `clientId` (string, optional): Client ID for the payment
- `className` (string, optional): Additional CSS classes
- `width` (string | number, optional): Modal width. Default: `"90%"`
- `height` (string | number, optional): Modal height. Default: `"90%"`
- `title` (string, optional): Modal title. Default: `"Ödeme"`
- `zIndex` (number, optional): Modal z-index. Default: `9999`

## Features

- 📦 Iframe-based payment widget (all payment logic handled in iframe)
- 🔒 Secure token-based authentication
- 📱 Responsive modal design
- 🎨 Customizable appearance (width, height, title, z-index)
- ⌨️ ESC key support for closing
- 🖱️ Click outside to close
- ⚡ Lightweight and easy to integrate
- 🔄 Loading states

## Widget URL

The widget creates an iframe URL by appending `/widget` to the host URL:

- Host: `https://api.example.com` → Widget URL: `https://api.example.com/widget?paymentId=...&token=...`
- Host: `https://api.example.com/` → Widget URL: `https://api.example.com/widget?paymentId=...&token=...`

The iframe URL includes the following query parameters:
- `paymentId`: Payment identifier
- `token`: Bearer token for authentication
- `clientId`: (optional) Client identifier

## Requirements

- React 18+ or 19+ (for React component)
- Vue 3+ (for Vue component)
- Backend API endpoint that serves the payment widget at `/widget` path

## License

MIT