@valuepay/react 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-03-25
+
+### Added
+
+- `<ValuePayButton />` component — drop-in pre-styled payment button with amount display
+- `<ValuePayProvider />` component — headless component with ref-based `initialize()` method
+- `useValuePay()` hook — programmatic API returning `{ initialize, isReady, isProcessing }`
+- `useScript()` hook — dynamic script loader with deduplication and cleanup
+- `generateTransactionRef()` utility — unique reference generator with configurable length
+- Full TypeScript support with exported types: `ValuePayConfig`, `ValuePayResponse`, `ValuePayCustomer`, `ValuePayCustomization`, `PaymentChannel`, `ValuePayStatus`, `UseValuePayReturn`, `ValuePayButtonProps`, `ValuePayProviderProps`, `ValuePayProviderRef`
+- Callback-based payment handling: `onSuccess`, `onClose`, `onCancelled`, `onCallback`, `onError`
+- Redirect-based payment handling via `redirectUrl` prop
+- Runtime config overrides via `initialize(overrides)` for dynamic amounts
+- Checkout modal customization (title, description, logo)
+- Payment channel selection (card, transfer, QR code, USSD, mobile money)
+- Custom metadata support via `metaData` prop
+- SSR-safe implementation (Next.js, Remix, Gatsby compatible)
+- Dual CJS + ESM output with tree-shaking support
+- Comprehensive test suite with 90%+ coverage
+- Double-payment prevention via `isProcessing` guard
+
+[1.0.0]: https://github.com/valuepayment/react-sdk/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Value Payment Solutions Limited
+
+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,435 @@
+# @valuepay/react
+
+> Official React SDK for [ValuePay](https://valuepayng.com) — accept payments in your React app with minimal setup.
+
+[![npm version](https://img.shields.io/npm/v/@valuepay/react.svg)](https://www.npmjs.com/package/@valuepay/react)
+[![license](https://img.shields.io/npm/l/@valuepay/react.svg)](LICENSE)
+[![coverage](https://img.shields.io/badge/coverage-90%25-brightgreen.svg)]()
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)]()
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [Option 1: Drop-in Button](#option-1-drop-in-button-simplest)
+  - [Option 2: Hook (Full Control)](#option-2-hook-full-control)
+  - [Option 3: Provider with Ref](#option-3-provider-with-ref-hidden-component)
+- [Redirect Mode](#redirect-mode)
+- [API Reference](#api-reference)
+  - [useValuePay](#usevaluepayconfig-valuepayconfig-usevaluepayreturn)
+  - [ValuePayButton](#valuepaybutton--props)
+  - [ValuePayProvider](#valuepayprovider--props)
+  - [ValuePayConfig](#valuepayconfig)
+  - [ValuePayResponse](#valuepayresponse)
+- [Dynamic Amounts](#dynamic-amounts)
+- [Payment Channels](#payment-channels)
+- [Customizing the Checkout Modal](#customizing-the-checkout-modal)
+- [Server-Side Verification](#server-side-verification)
+- [TypeScript](#typescript)
+- [Browser Support](#browser-support)
+- [Security](#security)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Installation
+
+```bash
+npm install @valuepay/react
+# or
+yarn add @valuepay/react
+# or
+pnpm add @valuepay/react
+```
+
+### Requirements
+
+- **React** `>=16.8.0` (hooks support required)
+- **React DOM** `>=16.8.0`
+
+---
+
+## Quick Start
+
+### Option 1: Drop-in Button (Simplest)
+
+```tsx
+import { ValuePayButton } from "@valuepay/react";
+
+function Checkout() {
+  return (
+    <ValuePayButton
+      publicKey="KP_your_public_key"
+      amount={5000}
+      customer={{ email: "jane@example.com", fullName: "Jane Doe" }}
+      onSuccess={(response) => {
+        console.log("Payment successful!", response.ref, response.status);
+      }}
+      onClose={(response) => {
+        console.log("Checkout closed", response);
+      }}
+      onCancelled={(response) => {
+        console.log("Payment cancelled", response);
+      }}
+    />
+  );
+}
+```
+
+The button renders as **"Pay ₦5,000 Now"** by default. Customize with `text`, `className`, `style`, or pass `children`.
+
+### Option 2: Hook (Full Control)
+
+```tsx
+import { useValuePay } from "@valuepay/react";
+
+function Checkout() {
+  const { initialize, isReady, isProcessing } = useValuePay({
+    publicKey: "KP_your_public_key",
+    amount: 10000,
+    customer: { email: "john@example.com", fullName: "John Doe" },
+    onSuccess: (response) => {
+      console.log("Paid!", response);
+      // response.ref, response.status, response.amount, etc.
+    },
+    onCancelled: (response) => console.log("Cancelled", response),
+    onClose: (response) => console.log("Closed", response),
+  });
+
+  return (
+    <button onClick={() => initialize()} disabled={!isReady || isProcessing}>
+      {isProcessing ? "Processing..." : "Pay ₦10,000"}
+    </button>
+  );
+}
+```
+
+### Option 3: Provider with Ref (Hidden Component)
+
+```tsx
+import { useRef } from "react";
+import { ValuePayProvider, ValuePayProviderRef } from "@valuepay/react";
+
+function Checkout() {
+  const payRef = useRef<ValuePayProviderRef>(null);
+
+  const handlePay = () => {
+    payRef.current?.initialize();
+  };
+
+  return (
+    <>
+      <ValuePayProvider
+        ref={payRef}
+        config={{
+          publicKey: "KP_your_public_key",
+          amount: 7500,
+          customer: { email: "alice@example.com", fullName: "Alice Smith" },
+          onSuccess: (response) => console.log("Success!", response),
+          onCancelled: (response) => console.log("Cancelled", response),
+        }}
+      />
+      <button onClick={handlePay}>Checkout</button>
+    </>
+  );
+}
+```
+
+---
+
+## Redirect Mode
+
+Instead of callbacks, you can redirect the user after payment:
+
+```tsx
+<ValuePayButton
+  publicKey="KP_your_public_key"
+  amount={5000}
+  customer={{ email: "jane@example.com", fullName: "Jane Doe" }}
+  redirectUrl="https://yoursite.com/payment/verify"
+/>
+```
+
+After payment, the user is redirected to:
+
+```
+https://yoursite.com/payment/verify?ref=VPS_TX_abc123&status=SUCCESS
+```
+
+Your server should then verify the transaction using the `ref` query parameter via the [ValuePay Verify API](https://developer.valuepayng.com/docs).
+
+---
+
+## API Reference
+
+### `useValuePay(config: ValuePayConfig): UseValuePayReturn`
+
+| Return         | Type                    | Description                                  |
+| -------------- | ----------------------- | -------------------------------------------- |
+| `initialize`   | `(overrides?) => void`  | Opens the ValuePay checkout modal            |
+| `isReady`      | `boolean`               | `true` when the ValuePay script has loaded   |
+| `isProcessing` | `boolean`               | `true` while a payment is in progress        |
+
+### `<ValuePayButton />` Props
+
+Extends `ValuePayConfig` with:
+
+| Prop        | Type             | Default                | Description          |
+| ----------- | ---------------- | ---------------------- | -------------------- |
+| `text`      | `string`         | `"Pay ₦{amount} Now"` | Button text          |
+| `className` | `string`         | —                      | CSS class            |
+| `style`     | `CSSProperties`  | —                      | Inline styles        |
+| `disabled`  | `boolean`        | `false`                | Disable button       |
+| `children`  | `ReactNode`      | —                      | Custom button content|
+
+### `<ValuePayProvider />` Props
+
+| Prop     | Type                      | Description                      |
+| -------- | ------------------------- | -------------------------------- |
+| `config` | `ValuePayConfig`          | Payment configuration            |
+| `ref`    | `Ref<ValuePayProviderRef>`| Exposes `initialize()` method    |
+
+### `ValuePayConfig`
+
+| Prop             | Type                         | Required | Default                              | Description                        |
+| ---------------- | ---------------------------- | -------- | ------------------------------------ | ---------------------------------- |
+| `publicKey`      | `string`                     | Yes      | —                                    | Your ValuePay public key           |
+| `amount`         | `number`                     | Yes      | —                                    | Amount in Naira                    |
+| `customer`       | `{ email, fullName, phone? }`| Yes      | —                                    | Customer details                   |
+| `currency`       | `string`                     | —        | `"NGN"`                              | Currency code                      |
+| `channels`       | `PaymentChannel[]`           | —        | `["card","transfer","qrcode","ussd"]`| Enabled channels                   |
+| `transactionRef` | `string`                     | —        | Auto-generated                       | Unique transaction reference       |
+| `redirectUrl`    | `string`                     | —        | —                                    | Redirect URL after payment         |
+| `metaData`       | `Record<string, unknown>`    | —        | —                                    | Custom metadata                    |
+| `customization`  | `{ title?, description?, logoUrl? }` | — | —                              | Checkout modal branding            |
+| `onSuccess`      | `(response) => void`         | —        | —                                    | Called on successful payment       |
+| `onClose`        | `(response) => void`         | —        | —                                    | Called when modal is closed        |
+| `onCancelled`    | `(response) => void`         | —        | —                                    | Called when payment is cancelled   |
+| `onCallback`     | `(response) => void`         | —        | —                                    | Called on any payment event        |
+| `onError`        | `(error) => void`            | —        | —                                    | Called on SDK errors               |
+| `scriptUrl`      | `string`                     | —        | Production CDN                       | Override ValuePay script URL       |
+
+### `ValuePayResponse`
+
+| Field            | Type               | Description                                                                                   |
+| ---------------- | ------------------ | --------------------------------------------------------------------------------------------- |
+| `ref`            | `string`           | Transaction reference                                                                         |
+| `transactionRef` | `string`           | Same as `ref`                                                                                 |
+| `status`         | `ValuePayStatus`   | `"SUCCESS"`, `"COMPLETED"`, `"FAILED"`, `"CANCELLED"`, `"DUPLICATE"`, `"PENDING"`             |
+| `amount`         | `number`           | Transaction amount                                                                            |
+| `currency`       | `string`           | Currency code                                                                                 |
+| `customer`       | `ValuePayCustomer` | Customer details                                                                              |
+| `paymentMethod`  | `string?`          | Payment method used                                                                           |
+| `validation`     | `{ status }?`      | Server-side validation result                                                                 |
+| `raw`            | `unknown?`         | Raw ValuePay response                                                                         |
+
+---
+
+## Dynamic Amounts
+
+Override any config at call time:
+
+```tsx
+const { initialize } = useValuePay({
+  publicKey: "KP_xxx",
+  amount: 0, // placeholder
+  customer: { email: "user@example.com", fullName: "User" },
+  onSuccess: (res) => console.log(res),
+});
+
+// Later, with dynamic amount:
+initialize({ amount: selectedProduct.price });
+```
+
+---
+
+## Payment Channels
+
+| Channel        | Value            |
+| -------------- | ---------------- |
+| Card           | `"card"`         |
+| Bank Transfer  | `"transfer"`     |
+| QR Code        | `"qrcode"`       |
+| USSD           | `"ussd"`         |
+| Mobile Money   | `"mobile_money"` |
+
+---
+
+## Customizing the Checkout Modal
+
+```tsx
+<ValuePayButton
+  publicKey="KP_xxx"
+  amount={2000}
+  customer={{ email: "user@example.com", fullName: "User" }}
+  customization={{
+    title: "My Store",
+    description: "Thanks for shopping with us!",
+    logoUrl: "https://mystore.com/logo.png",
+  }}
+  onSuccess={(res) => console.log(res)}
+/>
+```
+
+---
+
+## Server-Side Verification
+
+**Always verify transactions on your server.** Never trust client-side callbacks alone. Use the `ref` from the response:
+
+```ts
+// Backend (Node.js example)
+const response = await fetch(
+  "https://api.valuepayng.com/v1/transactions/verify",
+  {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${VALUEPAY_SECRET_KEY}`,
+    },
+    body: JSON.stringify({ tx_ref: transactionRef }),
+  },
+);
+const result = await response.json();
+```
+
+---
+
+## TypeScript
+
+All types are exported:
+
+```ts
+import type {
+  ValuePayConfig,
+  ValuePayResponse,
+  ValuePayCustomer,
+  ValuePayCustomization,
+  PaymentChannel,
+  ValuePayStatus,
+  UseValuePayReturn,
+  ValuePayButtonProps,
+  ValuePayProviderProps,
+  ValuePayProviderRef,
+} from "@valuepay/react";
+```
+
+---
+
+## Browser Support
+
+| Browser              | Minimum Version | Release Year |
+| -------------------- | --------------- | ------------ |
+| Chrome               | 49+             | 2016         |
+| Firefox              | 52+             | 2017         |
+| Safari               | 10+             | 2016         |
+| Edge                 | 15+             | 2017         |
+| Opera                | 36+             | 2016         |
+| Samsung Internet     | 5.0+            | 2016         |
+| iOS Safari           | 10+             | 2016         |
+| Android WebView      | 49+             | 2016         |
+| Internet Explorer    | 11 (with polyfills) | 2013     |
+
+The SDK targets **ES2018** and uses only features available in browsers from 2013 onwards (with appropriate polyfills for IE11). React 16.8+ is required for hooks support.
+
+### SSR Compatibility
+
+The SDK is SSR-safe and works with:
+- Next.js (Pages Router and App Router)
+- Remix
+- Gatsby
+- Any server-side rendering framework
+
+All DOM access is guarded with `typeof document !== "undefined"` and `typeof window !== "undefined"` checks.
+
+---
+
+## Security
+
+- **Never** expose your secret key in client-side code. Only use your **public key** with this SDK.
+- **Always** verify transactions server-side before fulfilling orders — client-side callbacks can be spoofed.
+- **Use HTTPS** in production to prevent man-in-the-middle attacks.
+- **Generate unique transaction references** per payment to prevent duplicate charges.
+- The SDK loads the ValuePay checkout script from `https://www.valuepayng.com` — ensure this domain is allowed in your Content Security Policy (CSP).
+- The SDK does **not** store, log, or transmit any sensitive payment data (card numbers, CVV, etc.). All payment processing happens within the ValuePay checkout modal.
+- Transaction references are generated using cryptographically sufficient randomness via `Math.random()` with alphanumeric characters.
+
+### Content Security Policy (CSP)
+
+If your application uses a Content Security Policy, add the following directives:
+
+```
+script-src 'self' https://www.valuepayng.com;
+frame-src 'self' https://www.valuepayng.com;
+```
+
+---
+
+## Error Handling
+
+The SDK provides an `onError` callback for handling SDK-level errors:
+
+```tsx
+<ValuePayButton
+  publicKey="KP_xxx"
+  amount={5000}
+  customer={{ email: "user@example.com", fullName: "User" }}
+  onError={(error) => {
+    console.error("Payment SDK error:", error.message);
+    // Handle error — e.g., show a toast notification
+  }}
+  onSuccess={(res) => console.log(res)}
+/>
+```
+
+Common error scenarios:
+- ValuePay script failed to load (network issue, blocked by CSP)
+- `window.ValuepayCheckout` is not available
+- Invalid configuration
+
+---
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/valuepayment/react-sdk.git
+cd react-sdk
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Lint
+npm run lint
+
+# Type check
+npm run typecheck
+
+# Build
+npm run build
+```
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a list of changes in each release.
+
+---
+
+## License
+
+MIT (c) [Value Payment Solutions Limited](https://valuepayng.com)

package/dist/cjs/components/ValuePayButton.js

@@ -0,0 +1,14 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var useValuePay = require('../hooks/useValuePay.js');
+
+const ValuePayButton = ({ text, className, style, disabled, children, ...config }) => {
+    const { initialize, isReady, isProcessing } = useValuePay.useValuePay(config);
+    const defaultText = `Pay \u20A6${config.amount.toLocaleString()} Now`;
+    const buttonText = children || text || defaultText;
+    return (jsxRuntime.jsx("button", { type: "button", onClick: () => initialize(), disabled: disabled || !isReady || isProcessing, className: className, style: style, "aria-busy": isProcessing, "aria-label": typeof buttonText === "string" ? buttonText : "Pay Now", children: isProcessing ? "Processing..." : buttonText }));
+};
+
+exports.ValuePayButton = ValuePayButton;
+//# sourceMappingURL=ValuePayButton.js.map

package/dist/cjs/components/ValuePayButton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValuePayButton.js","sources":["../../../../src/components/ValuePayButton.tsx"],"sourcesContent":["import React from \"react\";\nimport { useValuePay } from \"../hooks/useValuePay\";\nimport type { ValuePayButtonProps } from \"../types\";\n\nexport const ValuePayButton: React.FC<ValuePayButtonProps> = ({\n  text,\n  className,\n  style,\n  disabled,\n  children,\n  ...config\n}) => {\n  const { initialize, isReady, isProcessing } = useValuePay(config);\n\n  const defaultText = `Pay \\u20A6${config.amount.toLocaleString()} Now`;\n  const buttonText = children || text || defaultText;\n\n  return (\n    <button\n      type=\"button\"\n      onClick={() => initialize()}\n      disabled={disabled || !isReady || isProcessing}\n      className={className}\n      style={style}\n      aria-busy={isProcessing}\n      aria-label={typeof buttonText === \"string\" ? buttonText : \"Pay Now\"}\n    >\n      {isProcessing ? \"Processing...\" : buttonText}\n    </button>\n  );\n};\n"],"names":["useValuePay","_jsx"],"mappings":";;;;;MAIa,cAAc,GAAkC,CAAC,EAC5D,IAAI,EACJ,SAAS,EACT,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,GAAG,MAAM,EACV,KAAI;AACH,IAAA,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,GAAGA,uBAAW,CAAC,MAAM,CAAC;IAEjE,MAAM,WAAW,GAAG,CAAA,UAAA,EAAa,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,CAAA,IAAA,CAAM;AACrE,IAAA,MAAM,UAAU,GAAG,QAAQ,IAAI,IAAI,IAAI,WAAW;IAElD,QACEC,cAAA,CAAA,QAAA,EAAA,EACE,IAAI,EAAC,QAAQ,EACb,OAAO,EAAE,MAAM,UAAU,EAAE,EAC3B,QAAQ,EAAE,QAAQ,IAAI,CAAC,OAAO,IAAI,YAAY,EAC9C,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,KAAK,EAAA,WAAA,EACD,YAAY,EAAA,YAAA,EACX,OAAO,UAAU,KAAK,QAAQ,GAAG,UAAU,GAAG,SAAS,EAAA,QAAA,EAElE,YAAY,GAAG,eAAe,GAAG,UAAU,EAAA,CACrC;AAEb;;;;"}

package/dist/cjs/components/ValuePayProvider.js

@@ -0,0 +1,17 @@
+'use strict';
+
+var react = require('react');
+var useValuePay = require('../hooks/useValuePay.js');
+
+const ValuePayProvider = react.forwardRef(({ config }, ref) => {
+    const { initialize } = useValuePay.useValuePay(config);
+    react.useImperativeHandle(ref, () => ({
+        initialize: (overrides) => initialize(overrides),
+    }), [initialize]);
+    // Renders nothing — purely a data/logic container
+    return null;
+});
+ValuePayProvider.displayName = "ValuePayProvider";
+
+exports.ValuePayProvider = ValuePayProvider;
+//# sourceMappingURL=ValuePayProvider.js.map

package/dist/cjs/components/ValuePayProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValuePayProvider.js","sources":["../../../../src/components/ValuePayProvider.tsx"],"sourcesContent":["import { useImperativeHandle, forwardRef } from \"react\";\nimport { useValuePay } from \"../hooks/useValuePay\";\nimport type { ValuePayProviderProps, ValuePayProviderRef } from \"../types\";\n\nexport const ValuePayProvider = forwardRef<ValuePayProviderRef, ValuePayProviderProps>(\n  ({ config }, ref) => {\n    const { initialize } = useValuePay(config);\n\n    useImperativeHandle(\n      ref,\n      () => ({\n        initialize: (overrides) => initialize(overrides),\n      }),\n      [initialize],\n    );\n\n    // Renders nothing — purely a data/logic container\n    return null;\n  },\n);\n\nValuePayProvider.displayName = \"ValuePayProvider\";\n"],"names":["forwardRef","useValuePay","useImperativeHandle"],"mappings":";;;;;AAIO,MAAM,gBAAgB,GAAGA,gBAAU,CACxC,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,KAAI;IAClB,MAAM,EAAE,UAAU,EAAE,GAAGC,uBAAW,CAAC,MAAM,CAAC;AAE1C,IAAAC,yBAAmB,CACjB,GAAG,EACH,OAAO;QACL,UAAU,EAAE,CAAC,SAAS,KAAK,UAAU,CAAC,SAAS,CAAC;AACjD,KAAA,CAAC,EACF,CAAC,UAAU,CAAC,CACb;;AAGD,IAAA,OAAO,IAAI;AACb,CAAC;AAGH,gBAAgB,CAAC,WAAW,GAAG,kBAAkB;;;;"}

package/dist/cjs/hooks/useScript.js

@@ -0,0 +1,40 @@
+'use strict';
+
+var react = require('react');
+
+/**
+ * Dynamically loads an external script and tracks its loaded state.
+ * Deduplicates — won't inject the same script twice.
+ */
+const useScript = (src) => {
+    const [loaded, setLoaded] = react.useState(false);
+    const scriptRef = react.useRef(null);
+    react.useEffect(() => {
+        if (!src || typeof document === "undefined")
+            return;
+        // Check if already loaded
+        const existing = document.querySelector(`script[src="${src}"]`);
+        if (existing) {
+            setLoaded(true);
+            return;
+        }
+        const script = document.createElement("script");
+        script.src = src;
+        script.async = true;
+        script.onload = () => setLoaded(true);
+        script.onerror = () => {
+            console.error(`[@valuepay/react] Failed to load script: ${src}`);
+        };
+        document.body.appendChild(script);
+        scriptRef.current = script;
+        return () => {
+            if (scriptRef.current && document.body.contains(scriptRef.current)) {
+                document.body.removeChild(scriptRef.current);
+            }
+        };
+    }, [src]);
+    return loaded;
+};
+
+exports.useScript = useScript;
+//# sourceMappingURL=useScript.js.map

package/dist/cjs/hooks/useScript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScript.js","sources":["../../../../src/hooks/useScript.ts"],"sourcesContent":["import { useEffect, useState, useRef } from \"react\";\n\n/**\n * Dynamically loads an external script and tracks its loaded state.\n * Deduplicates — won't inject the same script twice.\n */\nexport const useScript = (src: string): boolean => {\n  const [loaded, setLoaded] = useState(false);\n  const scriptRef = useRef<HTMLScriptElement | null>(null);\n\n  useEffect(() => {\n    if (!src || typeof document === \"undefined\") return;\n\n    // Check if already loaded\n    const existing = document.querySelector<HTMLScriptElement>(`script[src=\"${src}\"]`);\n    if (existing) {\n      setLoaded(true);\n      return;\n    }\n\n    const script = document.createElement(\"script\");\n    script.src = src;\n    script.async = true;\n    script.onload = () => setLoaded(true);\n    script.onerror = () => {\n      console.error(`[@valuepay/react] Failed to load script: ${src}`);\n    };\n\n    document.body.appendChild(script);\n    scriptRef.current = script;\n\n    return () => {\n      if (scriptRef.current && document.body.contains(scriptRef.current)) {\n        document.body.removeChild(scriptRef.current);\n      }\n    };\n  }, [src]);\n\n  return loaded;\n};\n"],"names":["useState","useRef","useEffect"],"mappings":";;;;AAEA;;;AAGG;AACI,MAAM,SAAS,GAAG,CAAC,GAAW,KAAa;IAChD,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAGA,cAAQ,CAAC,KAAK,CAAC;AAC3C,IAAA,MAAM,SAAS,GAAGC,YAAM,CAA2B,IAAI,CAAC;IAExDC,eAAS,CAAC,MAAK;AACb,QAAA,IAAI,CAAC,GAAG,IAAI,OAAO,QAAQ,KAAK,WAAW;YAAE;;QAG7C,MAAM,QAAQ,GAAG,QAAQ,CAAC,aAAa,CAAoB,CAAA,YAAA,EAAe,GAAG,CAAA,EAAA,CAAI,CAAC;QAClF,IAAI,QAAQ,EAAE;YACZ,SAAS,CAAC,IAAI,CAAC;YACf;QACF;QAEA,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC;AAC/C,QAAA,MAAM,CAAC,GAAG,GAAG,GAAG;AAChB,QAAA,MAAM,CAAC,KAAK,GAAG,IAAI;QACnB,MAAM,CAAC,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC;AACrC,QAAA,MAAM,CAAC,OAAO,GAAG,MAAK;AACpB,YAAA,OAAO,CAAC,KAAK,CAAC,4CAA4C,GAAG,CAAA,CAAE,CAAC;AAClE,QAAA,CAAC;AAED,QAAA,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;AACjC,QAAA,SAAS,CAAC,OAAO,GAAG,MAAM;AAE1B,QAAA,OAAO,MAAK;AACV,YAAA,IAAI,SAAS,CAAC,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE;gBAClE,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,OAAO,CAAC;YAC9C;AACF,QAAA,CAAC;AACH,IAAA,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;AAET,IAAA,OAAO,MAAM;AACf;;;;"}

package/dist/cjs/hooks/useValuePay.js

@@ -0,0 +1,90 @@
+'use strict';
+
+var react = require('react');
+var useScript = require('./useScript.js');
+var helpers = require('../utils/helpers.js');
+var constants = require('../utils/constants.js');
+
+const useValuePay = (config) => {
+    const scriptUrl = config.scriptUrl || constants.DEFAULT_SCRIPT_URL;
+    const isReady = useScript.useScript(scriptUrl);
+    const [isProcessing, setIsProcessing] = react.useState(false);
+    const configRef = react.useRef(config);
+    configRef.current = config;
+    const initialize = react.useCallback((overrides) => {
+        var _a;
+        const cfg = configRef.current;
+        if (typeof window === "undefined" || !window.ValuepayCheckout) {
+            (_a = cfg.onError) === null || _a === void 0 ? void 0 : _a.call(cfg, new Error("ValuePay script not loaded. Ensure the script URL is accessible."));
+            return;
+        }
+        if (isProcessing)
+            return;
+        setIsProcessing(true);
+        const normalized = helpers.normalizeConfig(cfg, overrides);
+        const ref = normalized.transactionRef;
+        window.ValuepayCheckout({
+            ...normalized,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            oncallback: (response) => {
+                var _a, _b;
+                const res = helpers.normalizeResponse(response, ref, cfg);
+                setIsProcessing(false);
+                if (cfg.redirectUrl) {
+                    const url = new URL(cfg.redirectUrl);
+                    url.searchParams.set("ref", res.ref);
+                    url.searchParams.set("status", res.status);
+                    window.location.href = url.toString();
+                    return;
+                }
+                (_a = cfg.onCallback) === null || _a === void 0 ? void 0 : _a.call(cfg, res);
+                if (res.status === "SUCCESS" || res.status === "COMPLETED") {
+                    (_b = cfg.onSuccess) === null || _b === void 0 ? void 0 : _b.call(cfg, res);
+                }
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            onCancelled: (response) => {
+                var _a;
+                const res = helpers.normalizeResponse(response, ref, cfg);
+                res.status = "CANCELLED";
+                setIsProcessing(false);
+                if (cfg.redirectUrl) {
+                    const url = new URL(cfg.redirectUrl);
+                    url.searchParams.set("ref", res.ref);
+                    url.searchParams.set("status", "CANCELLED");
+                    window.location.href = url.toString();
+                    return;
+                }
+                (_a = cfg.onCancelled) === null || _a === void 0 ? void 0 : _a.call(cfg, res);
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            onAborted: (response) => {
+                var _a;
+                const res = helpers.normalizeResponse(response, ref, cfg);
+                res.status = "CANCELLED";
+                setIsProcessing(false);
+                (_a = cfg.onCancelled) === null || _a === void 0 ? void 0 : _a.call(cfg, res);
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            onClosed: (response) => {
+                var _a;
+                const res = helpers.normalizeResponse(response, ref, cfg);
+                setIsProcessing(false);
+                if (cfg.redirectUrl) {
+                    const url = new URL(cfg.redirectUrl);
+                    url.searchParams.set("ref", res.ref);
+                    url.searchParams.set("status", "CLOSED");
+                    window.location.href = url.toString();
+                    return;
+                }
+                (_a = cfg.onClose) === null || _a === void 0 ? void 0 : _a.call(cfg, res);
+            },
+        });
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [isReady, isProcessing]);
+    return { initialize, isReady, isProcessing };
+};
+
+exports.useValuePay = useValuePay;
+//# sourceMappingURL=useValuePay.js.map