@reevit/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Reevit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,211 @@
+# @reevit/react
+
+Unified Payment Widget for React Applications. Accept card and mobile money payments with a single integration.
+
+## Installation
+
+```bash
+npm install @reevit/react
+```
+
+## Quick Start
+
+The simplest way to integrate Reevit is using the `ReevitCheckout` component.
+
+```tsx
+import { ReevitCheckout } from '@reevit/react';
+import '@reevit/react/styles.css';
+
+function App() {
+  return (
+    <ReevitCheckout
+      publicKey="pk_test_your_key"
+      amount={10000} // Amount in smallest unit (e.g., pesewas for GHS)
+      currency="GHS"
+      email="customer@example.com"
+      onSuccess={(result) => {
+        console.log('Payment success!', result);
+        alert(`Payment of ${result.currency} ${result.amount/100} successful!`);
+      }}
+      onError={(error) => {
+        console.error('Payment failed:', error.message);
+      }}
+    >
+      <button className="my-pay-button">Pay GHS 100.00</button>
+    </ReevitCheckout>
+  );
+}
+```
+
+## Custom Theme
+
+You can customize the look and feel of the checkout widget to match your brand.
+
+```tsx
+<ReevitCheckout
+  theme={{
+    primaryColor: '#6200EE',
+    backgroundColor: '#F5F5F5',
+    textColor: '#000000',
+    borderRadius: '12px',
+    fontFamily: "'Segoe UI', Roboto, sans-serif",
+    darkMode: true,
+  }}
+  // ...other props
+>
+  <button>Secure Checkout</button>
+</ReevitCheckout>
+```
+
+## Advanced Usage: useReevit Hook
+
+For full control over the payment flow, use the `useReevit` hook. This allows you to build your own custom UI while Reevit handles the state management and API communication.
+
+```tsx
+import { useReevit } from '@reevit/react';
+
+function CustomCheckout() {
+  const {
+    status,        // 'idle' | 'loading' | 'ready' | 'method_selected' | 'processing' | 'success' | 'failed'
+    initialize,    // Start the process
+    selectMethod,  // Pick 'card' or 'mobile_money'
+    processPayment, // Confirm payment
+    error,
+    isLoading
+  } = useReevit({
+    config: {
+      publicKey: 'pk_test_xxx',
+      amount: 5000,
+      currency: 'GHS',
+    },
+    onSuccess: (res) => console.log('Done!', res),
+  });
+
+  if (status === 'loading') return <Spinner />;
+
+  return (
+    <div>
+      <button onClick={() => initialize()}>Start Checkout</button>
+      {status === 'ready' && (
+        <>
+          <button onClick={() => selectMethod('card')}>Card</button>
+          <button onClick={() => selectMethod('mobile_money')}>Mobile Money</button>
+        </>
+      )}
+    </div>
+  );
+}
+```
+
+## Browser Support
+
+- Chrome, Firefox, Safari, Edge (latest 2 versions)
+- Mobile Safari and Chrome on Android/iOS
+
+## Props Reference
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `publicKey` | `string` | **Required**. Your project's public key (pk_test_... or pk_live_...) |
+| `amount` | `number` | **Required**. Amount in the smallest unit (e.g., 500 for 5.00) |
+| `currency` | `string` | **Required**. 3-letter ISO currency code (GHS, NGN, USD, etc.) |
+| `email` | `string` | Customer's email address |
+| `phone` | `string` | Customer's phone number (recommended for Mobile Money) |
+| `reference` | `string` | Your own unique transaction reference |
+| `metadata` | `object` | Key-value pairs to store with the transaction |
+| `paymentMethods` | `string[]` | List of enabled methods: `['card', 'mobile_money', 'bank_transfer']` |
+| `theme` | `ReevitTheme` | Customization options for the widget |
+| `onSuccess` | `function` | Called when the payment is successfully processed |
+| `onError` | `function` | Called when an error occurs |
+| `onClose` | `function` | Called when the user dismisses the widget |
+
+## PSP Bridges
+
+For advanced use cases, you can use individual PSP bridges directly. These provide React components for each payment processor.
+
+### Stripe
+
+```tsx
+import { StripeBridge } from '@reevit/react';
+
+<StripeBridge
+  publishableKey="pk_test_xxx"
+  clientSecret="pi_xxx_secret_xxx" // From your backend
+  amount={5000}
+  currency="USD"
+  onSuccess={(result) => console.log('Paid:', result.paymentIntentId)}
+  onError={(err) => console.error(err.message)}
+/>
+```
+
+### Monnify (Nigeria)
+
+```tsx
+import { MonnifyBridge } from '@reevit/react';
+
+<MonnifyBridge
+  apiKey="MK_TEST_xxx"
+  contractCode="1234567890"
+  amount={5000}
+  currency="NGN"
+  reference="TXN_12345"
+  customerName="John Doe"
+  customerEmail="john@example.com"
+  isTestMode={true}
+  onSuccess={(result) => console.log('Paid:', result.transactionReference)}
+  onError={(err) => console.error(err.message)}
+/>
+```
+
+### M-Pesa (Kenya/Tanzania)
+
+M-Pesa uses STK Push - the customer receives a prompt on their phone to authorize the payment.
+
+```tsx
+import { MPesaBridge, useMPesaStatusPolling } from '@reevit/react';
+
+function MpesaPayment() {
+  const [checkoutId, setCheckoutId] = useState(null);
+  
+  const { startPolling } = useMPesaStatusPolling(
+    '/api/mpesa/status',
+    checkoutId,
+    {
+      onSuccess: (result) => console.log('Paid:', result.transactionId),
+      onFailed: (err) => console.error(err.message),
+      onTimeout: () => console.log('Timed out'),
+    }
+  );
+
+  return (
+    <MPesaBridge
+      apiEndpoint="/api/mpesa/stk-push"
+      phoneNumber="254712345678"
+      amount={500}
+      currency="KES"
+      reference="TXN_12345"
+      onInitiated={(id) => {
+        setCheckoutId(id);
+        startPolling();
+      }}
+      onSuccess={(result) => console.log('Paid!')}
+      onError={(err) => console.error(err.message)}
+    />
+  );
+}
+```
+
+## Supported PSPs
+
+| Provider | Countries | Payment Methods |
+|----------|-----------|-----------------|
+| Paystack | NG, GH, ZA, KE | Card, Mobile Money, Bank |
+| Flutterwave | NG, GH, KE, ZA + | Card, Mobile Money, Bank |
+| Hubtel | GH | Mobile Money |
+| Stripe | Global (50+) | Card, Apple Pay, Google Pay |
+| Monnify | NG | Card, Bank Transfer, USSD |
+| M-Pesa | KE, TZ | Mobile Money (STK Push) |
+
+## License
+
+MIT © [Reevit](https://reevit.io)