@openhive-eu/payment 1.0.0-beta.3 → 1.0.0-beta.5

package/README.md

@@ -0,0 +1,150 @@
+# @openhive-eu/payment
+
+Payment terminal widget — Lit web component with optional React wrapper.
+
+📖 **[Full documentation](https://docs.openhive.eu/docs/services/payment/intro)**
+
+## Installation
+
+```bash
+npm install @openhive-eu/payment
+```
+
+## Usage
+
+### Vanilla / HTML
+
+```html
+<script type="module">
+  import '@openhive-eu/payment';
+  import '@openhive-eu/payment/styles.css';
+</script>
+
+<openhive-pay
+  token="your-api-token"
+  locale="en"
+  default-amount="150"
+  default-reference="FA-2025-001"
+></openhive-pay>
+
+<script>
+  document.querySelector('openhive-pay').addEventListener('request-to-pay', (e) => {
+    console.log(e.detail); // RequestToPay
+  });
+</script>
+```
+
+### Via CDN
+
+CSS is bundled inside the JS — only one file to load.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@openhive-eu/payment/dist/index.min.js"></script>
+
+<openhive-pay token="your-api-token"></openhive-pay>
+```
+
+### React
+
+```tsx
+import { Payment } from '@openhive-eu/payment/react';
+import '@openhive-eu/payment/styles.css';
+
+function App() {
+  return (
+    <Payment
+      token="your-api-token"
+      locale="en"
+      defaultAmount="150"
+      defaultReference="FA-2025-001"
+      onRequestToPay={(e) => console.log(e.detail)}
+      onClose={() => console.log('closed')}
+    />
+  );
+}
+```
+
+## Properties
+
+| Attribute            | Type      | Default | Description                                      |
+|----------------------|-----------|---------|--------------------------------------------------|
+| `token`              | `string`  | `""`    | API authentication token                         |
+| `locale`             | `string`  | `"fr"`  | UI language (`"fr"` or `"en"`)                   |
+| `currency`           | `string`  | `"EUR"` | Currency                                         |
+| `default-amount`     | `string`  | `""`    | Pre-filled amount                                |
+| `default-reference`  | `string`  | `""`    | Pre-filled order reference                       |
+| `read-only-amount`   | `boolean` | `false` | Lock the amount field                            |
+| `customer-email`     | `string`  | `""`    | Pre-filled customer email                        |
+| `customer-phone`     | `string`  | `""`    | Pre-filled customer phone number                 |
+| `customer-name`      | `string`  | `""`    | Pre-filled customer name                         |
+| `pay-client-ref`     | `string`  | `""`    | Reference to a global `PayClient` instance       |
+
+> In React, kebab-case attributes become camelCase (`default-amount` → `defaultAmount`).
+
+## Events
+
+| Event             | Type                          | Description                                  |
+|-------------------|-------------------------------|----------------------------------------------|
+| `request-to-pay`  | `CustomEvent<RequestToPay>`   | Fired when the form is submitted             |
+| `close`           | `Event`                       | Fired when the user closes the widget        |
+
+### `RequestToPay` type
+
+```ts
+type RequestToPay = {
+  order_reference: string;
+  amount: number;          // in cents
+  currency: string;
+  method: string;
+  partner: 'adyen' | 'stripe' | 'fintecture';
+  channel: 'email' | 'sms' | 'link';
+  customer_contact: string;
+}
+```
+
+## CSS Customization
+
+The widget adapts to your SaaS brand via **CSS variables**.
+
+### Target all OpenHive widgets
+
+```css
+:root {
+  --openhive-primary: #your-brand;
+  --openhive-radius: 0.5rem;
+}
+```
+
+### Target the payment widget only
+
+```css
+openhive-pay {
+  --pay-primary: #your-brand;
+  --pay-primary-foreground: #ffffff;
+}
+```
+
+### Available variables
+
+| Variable                      | Default                              |
+|-------------------------------|--------------------------------------|
+| `--pay-primary`               | `var(--openhive-primary)`            |
+| `--pay-primary-foreground`    | `var(--openhive-primary-foreground)` |
+| `--pay-background`            | `var(--openhive-background)`         |
+| `--pay-foreground`            | `var(--openhive-foreground)`         |
+| `--pay-muted`                 | `var(--openhive-muted)`              |
+| `--pay-muted-foreground`      | `var(--openhive-muted-foreground)`   |
+| `--pay-accent`                | `var(--openhive-accent)`             |
+| `--pay-accent-foreground`     | `var(--openhive-accent-foreground)`  |
+| `--pay-border`                | `var(--openhive-border)`             |
+| `--pay-input`                 | `var(--openhive-input)`              |
+| `--pay-ring`                  | `var(--openhive-ring)`               |
+| `--pay-radius`                | `var(--openhive-radius)`             |
+
+## npm tags
+
+| Tag       | Command                                     | Use case                          |
+|-----------|---------------------------------------------|-----------------------------------|
+| `latest`  | `npm install @openhive-eu/payment`          | Production                        |
+| `beta`    | `npm install @openhive-eu/payment@beta`     | Staging / pre-release validation  |
+| `next`    | `npm install @openhive-eu/payment@next`     | Early testing                     |