@zahlen/checkout-react 0.1.0

package/README.md

@@ -0,0 +1,219 @@
+# @zahlen/checkout-react
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/@zahlen/checkout-react?style=flat-square" alt="npm version" />
+  <img src="https://img.shields.io/npm/l/@zahlen/checkout-react?style=flat-square" alt="license" />
+</p>
+
+<p align="center">
+  <strong>React components for Zahlen Checkout</strong>
+  <br />
+  Hooks • Components • Full TypeScript support
+</p>
+
+---
+
+## 🚀 Installation
+
+```bash
+npm install @zahlen/checkout-react @zahlen/checkout
+# or
+yarn add @zahlen/checkout-react @zahlen/checkout
+```
+
+---
+
+## 📖 Quick Start
+
+### Option 1: Simple Button (Easiest)
+
+```tsx
+import { ZahlenProvider, ZahlenButton } from '@zahlen/checkout-react';
+
+function App() {
+  return (
+    <ZahlenProvider apiKey="pk_live_your_api_key">
+      <ProductPage />
+    </ZahlenProvider>
+  );
+}
+
+function ProductPage() {
+  return (
+    <ZahlenButton
+      amount={499900}        // ₦4,999 in kobo
+      currency="NGN"
+      description="Premium Plan"
+      onSuccess={(result) => {
+        console.log('Paid!', result);
+        // Redirect to success page
+      }}
+      onError={(error) => {
+        toast.error(error.message);
+      }}
+    >
+      💳 Pay ₦4,999
+    </ZahlenButton>
+  );
+}
+```
+
+### Option 2: useZahlen Hook (Recommended)
+
+```tsx
+import { ZahlenProvider, useZahlen } from '@zahlen/checkout-react';
+
+function App() {
+  return (
+    <ZahlenProvider apiKey="pk_live_your_api_key" theme="dark">
+      <ProductPage />
+    </ZahlenProvider>
+  );
+}
+
+function ProductPage() {
+  const { openCheckout, isProcessing } = useZahlen();
+
+  const handleBuy = async () => {
+    try {
+      const result = await openCheckout({
+        amount: 499900,
+        currency: 'NGN',
+        description: 'Premium Plan',
+      });
+      console.log('Payment successful!', result);
+      router.push('/success');
+    } catch (error) {
+      console.error('Payment failed:', error);
+    }
+  };
+
+  return (
+    <button onClick={handleBuy} disabled={isProcessing}>
+      {isProcessing ? 'Processing...' : 'Buy Now'}
+    </button>
+  );
+}
+```
+
+### Option 3: Controlled Component (Full Control)
+
+```tsx
+import { useState } from 'react';
+import { ZahlenCheckout } from '@zahlen/checkout-react';
+import { Zahlen } from '@zahlen/checkout';
+
+// Initialize once at app entry
+Zahlen.init({ apiKey: 'pk_live_your_api_key' });
+
+function ProductPage() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>Pay Now</button>
+
+      <ZahlenCheckout
+        open={isOpen}
+        onClose={() => setIsOpen(false)}
+        amount={499900}
+        currency="NGN"
+        description="Premium Plan"
+        onSuccess={(result) => {
+          setIsOpen(false);
+          router.push('/success');
+        }}
+        onError={(error) => {
+          console.error(error);
+        }}
+      />
+    </>
+  );
+}
+```
+
+---
+
+## 📚 API Reference
+
+### `<ZahlenProvider>`
+
+Wrap your app with this provider to use Zahlen hooks.
+
+```tsx
+<ZahlenProvider
+  apiKey="pk_live_xxx"     // Required
+  theme="dark"             // Optional: 'dark' | 'light' | 'auto'
+>
+  {children}
+</ZahlenProvider>
+```
+
+### `useZahlen()`
+
+Hook to access Zahlen functionality.
+
+```tsx
+const {
+  isInitialized,  // boolean - whether SDK is ready
+  isProcessing,   // boolean - whether payment is in progress
+  openCheckout,   // (options) => Promise<PaymentResult>
+  closeCheckout,  // () => void
+  setTheme,       // (theme) => void
+} = useZahlen();
+```
+
+### `<ZahlenButton>`
+
+Pre-styled checkout button.
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `amount` | `number` | ✅ | Amount in smallest unit |
+| `currency` | `string` | ✅ | ISO currency code |
+| `description` | `string` | | Payment description |
+| `customerEmail` | `string` | | Customer email |
+| `metadata` | `object` | | Custom metadata |
+| `onSuccess` | `function` | | Success callback |
+| `onError` | `function` | | Error callback |
+| `onClose` | `function` | | Close callback |
+| `className` | `string` | | CSS class |
+| `style` | `object` | | Inline styles |
+| `disabled` | `boolean` | | Disable button |
+
+### `<ZahlenCheckout>`
+
+Controlled checkout component.
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `open` | `boolean` | ✅ | Control modal visibility |
+| `onClose` | `function` | ✅ | Close callback |
+| `amount` | `number` | ✅ | Amount in smallest unit |
+| `currency` | `string` | ✅ | ISO currency code |
+| `onSuccess` | `function` | ✅ | Success callback |
+| `onError` | `function` | | Error callback |
+| `description` | `string` | | Payment description |
+
+---
+
+## 🎨 Customization
+
+```tsx
+import { Zahlen } from '@zahlen/checkout';
+
+// After init, customize theme
+Zahlen.init({
+  apiKey: 'pk_live_xxx',
+  customStyles: {
+    '--zahlen-primary': '#FF6B6B',
+    '--zahlen-bg': '#1A1A2E',
+  }
+});
+```
+
+---
+
+## 📄 License
+
+MIT © Zahlen

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/index";