@dekin_dev/react-checkout 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Veqta Space
+
+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,332 @@
+# @dekin_dev/react-checkout
+
+A lightweight, provider-agnostic React modal for embedding a **gateway-hosted checkout page** in an iframe — built for Hubtel, Moolre, PaySwitch, and any other payment gateway with a hosted checkout URL.
+
+> **This is a community/third-party tool. It is not an official Hubtel, Moolre, or PaySwitch SDK**, and it is not affiliated with or endorsed by any of them.
+
+This package does **not** implement any payment gateway's API. You obtain a checkout URL from your gateway's own server-side integration (using your account credentials on your backend), and this package gives you a polished, accessible, responsive modal to display it in — so you stop rebuilding the same iframe modal for every project.
+
+```tsx
+import { Checkout } from "@dekin_dev/react-checkout";
+import "@dekin_dev/react-checkout/styles.css";
+
+<Checkout
+  provider="hubtel"
+  checkoutUrl={checkoutUrl}
+  open={open}
+  onClose={() => setOpen(false)}
+/>;
+```
+
+- 🪶 Lightweight — ~4KB gzipped JS, ~1.3KB gzipped CSS, React as the only peer dependency
+- 🧩 Provider-agnostic core — built-in presets for Hubtel/Moolre/PaySwitch, plus a fully custom provider shape for anything else
+- 🎨 Works with plain CSS out of the box, and just as well with Tailwind utility classes
+- ♿ Accessible — `role="dialog"`, focus trapping/restoration, Escape to close, keyboard support
+- 📱 Mobile-first — goes full-screen under 640px so mobile money/OTP/card flows have room to breathe
+- 🔒 Secure by default — URL validation, strict `postMessage` origin checks, no gateway credentials anywhere near the frontend
+- 🖥️ SSR-safe — no `window`/`document` access outside effects; works in Next.js, Remix, CRA, plain Vite
+
+---
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Provider guides](#provider-guides)
+- [Custom providers](#custom-providers)
+- [Payment success handling — read this](#payment-success-handling--read-this)
+- [Styling — plain CSS or Tailwind](#styling--plain-css-or-tailwind)
+- [`useCheckout()` hook](#usecheckout-hook)
+- [`CheckoutButton`](#checkoutbutton)
+- [Props reference](#props-reference)
+- [Accessibility](#accessibility)
+- [SSR](#ssr)
+- [Security notes](#security-notes)
+- [Gateway research notes](#gateway-research-notes)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+
+## Installation
+
+```bash
+npm install @dekin_dev/react-checkout
+```
+
+React 18+ (and React 19) are peer dependencies — install them yourself if you haven't already. Nothing else is required; you do **not** need Tailwind.
+
+## Quick start
+
+```tsx
+import { useState } from "react";
+import { Checkout } from "@dekin_dev/react-checkout";
+import "@dekin_dev/react-checkout/styles.css";
+
+function PaymentPage() {
+  const [open, setOpen] = useState(false);
+  const [checkoutUrl, setCheckoutUrl] = useState<string | null>(null);
+
+  async function handlePay() {
+    // Your backend calls the gateway's API and returns a checkout URL.
+    const res = await fetch("/api/create-checkout", { method: "POST" });
+    const { checkoutUrl } = await res.json();
+    setCheckoutUrl(checkoutUrl);
+    setOpen(true);
+  }
+
+  return (
+    <>
+      <button onClick={handlePay}>Pay now</button>
+      {checkoutUrl && (
+        <Checkout
+          provider="hubtel"
+          checkoutUrl={checkoutUrl}
+          open={open}
+          onClose={() => setOpen(false)}
+        />
+      )}
+    </>
+  );
+}
+```
+
+Never call a gateway's API directly from the browser with a secret key — `checkoutUrl` must come from your own backend.
+
+## Provider guides
+
+For all three built-in providers, the pattern is the same: **your backend creates the checkout URL using that gateway's own API and your account credentials; this component only displays it.**
+
+### Hubtel
+
+Your backend integrates with Hubtel's Online Checkout API (their `payproxyapi.hubtel.com` initiate endpoint) to create a checkout URL, configuring:
+
+- a `callbackUrl` — a server-to-server webhook your backend exposes to receive the final payment status
+- a `returnUrl` / `cancellationUrl` — where the customer's browser is redirected after paying/cancelling
+
+```tsx
+<Checkout
+  provider="hubtel"
+  checkoutUrl={checkoutUrl}
+  open={open}
+  onClose={() => setOpen(false)}
+/>
+```
+
+Hubtel's documented flow is redirect + webhook based, not a `postMessage` protocol for a plain embedded URL — see [Gateway research notes](#gateway-research-notes).
+
+### Moolre
+
+Your backend uses Moolre's Collections/Checkout API to generate a hosted checkout URL, then passes it straight through:
+
+```tsx
+<Checkout
+  provider="moolre"
+  checkoutUrl={checkoutUrl}
+  open={open}
+  onClose={() => setOpen(false)}
+/>
+```
+
+### PaySwitch
+
+Your backend uses PaySwitch's API (PayLink or TheTeller) to obtain a checkout/payment-link URL:
+
+```tsx
+<Checkout
+  provider="payswitch"
+  checkoutUrl={checkoutUrl}
+  open={open}
+  onClose={() => setOpen(false)}
+/>
+```
+
+## Custom providers
+
+Not using Hubtel/Moolre/PaySwitch, or want different defaults? Pass an inline provider config instead of a string:
+
+```tsx
+<Checkout
+  provider={{
+    name: "my-gateway",
+    allowedOrigins: ["https://checkout.mygateway.com"],
+    defaultTitle: "Complete your payment",
+  }}
+  checkoutUrl={checkoutUrl}
+  open={open}
+  onClose={() => setOpen(false)}
+/>
+```
+
+If you control the checkout page yourself and want it to talk back to the parent window, add a `messageHandler` to normalize its `postMessage` events:
+
+```tsx
+provider={{
+  name: "my-gateway",
+  allowedOrigins: ["https://checkout.mygateway.com"],
+  messageHandler: (event) => {
+    if (event.data?.kind !== "payment-event") return null;
+    return { type: event.data.status, provider: "my-gateway", origin: event.origin };
+  },
+}}
+```
+
+Messages are only ever accepted from origins you list in `allowedOrigins` — everything else is dropped before your `messageHandler` ever sees it.
+
+## Payment success handling — read this
+
+**This component's frontend events (including `onSuccess`) must never be treated as final proof of payment.** A modal closing, or a message arriving, only means something happened in the browser — it says nothing about whether the payment actually settled.
+
+The right architecture:
+
+```text
+Checkout UI (this package)
+       │
+       ▼
+   Gateway
+       │
+       ▼
+Gateway webhook  ─────────────▶  Merchant backend
+                                       │
+                                       ▼
+                                Verify with the gateway's API
+                                       │
+                                       ▼
+                              Update the order, notify the frontend
+```
+
+Concretely:
+
+- None of the built-in providers (Hubtel, Moolre, PaySwitch) have a **documented** `postMessage` protocol for a plain embedded checkout URL, so `onSuccess`/`onFailure`/`onCancel` never fire for them today — this package does not invent gateway behavior that isn't verified. Use `onClose` to prompt the user, then poll or subscribe for your backend's own confirmation (which it gets from the gateway's webhook).
+- For a `custom` provider where you control the checkout page and its `postMessage` contract, `onSuccess`/`onFailure`/`onCancel` fire based on your own `messageHandler` — but still verify server-side before fulfilling an order. A compromised or buggy checkout page could otherwise "confirm" a payment that never happened.
+
+## Styling — plain CSS or Tailwind
+
+Import the stylesheet once:
+
+```tsx
+import "@dekin_dev/react-checkout/styles.css";
+```
+
+Every class is namespaced (`.vq-checkout-*`), so it won't collide with your app's CSS or a Tailwind `preflight` reset, and colors/spacing are exposed as CSS variables on `.vq-checkout-root` for easy re-theming:
+
+```css
+.vq-checkout-root {
+  --vq-radius: 8px;
+  --vq-focus-ring: #16a34a;
+}
+```
+
+Every visual piece also accepts a `className` so you can layer on **Tailwind utilities** exactly like any other class list — no extra configuration needed:
+
+```tsx
+<Checkout
+  checkoutUrl={checkoutUrl}
+  open={open}
+  onClose={() => setOpen(false)}
+  className="rounded-3xl ring-4 ring-indigo-200"
+  overlayClassName="backdrop-blur-sm"
+/>
+```
+
+`theme="light" | "dark" | "auto"` switches the built-in palette; `"auto"` follows `prefers-color-scheme`.
+
+## `useCheckout()` hook
+
+An imperative alternative for when you don't want to manage `open` state yourself:
+
+```tsx
+import { useCheckout } from "@dekin_dev/react-checkout";
+
+function Payment() {
+  const { openCheckout, CheckoutModal } = useCheckout();
+
+  return (
+    <>
+      <button onClick={() => openCheckout({ provider: "hubtel", checkoutUrl })}>Pay now</button>
+      <CheckoutModal />
+    </>
+  );
+}
+```
+
+## `CheckoutButton`
+
+For the simplest possible integration — a trigger button and the modal in one component:
+
+```tsx
+import { CheckoutButton } from "@dekin_dev/react-checkout";
+
+<CheckoutButton provider="hubtel" checkoutUrl={checkoutUrl}>
+  Pay with Hubtel
+</CheckoutButton>;
+```
+
+## Props reference
+
+The primary component is `<Checkout />`:
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `open` | `boolean` | — | required |
+| `checkoutUrl` | `string` | — | required; validated before use |
+| `provider` | `"hubtel" \| "moolre" \| "payswitch" \| "custom" \| CheckoutProviderConfig` | `"custom"` | |
+| `providerConfig` | `Partial<CheckoutProviderConfig>` | — | overrides merged over the preset |
+| `onOpen` / `onClose` / `onLoad` / `onError` | functions | — | lifecycle callbacks |
+| `onMessage` / `onSuccess` / `onFailure` / `onCancel` | functions | — | only fire for origin-validated, provider-normalized messages |
+| `title` / `description` | `string` | provider default / — | |
+| `showCloseButton` | `boolean` | `true` | |
+| `closeOnOverlayClick` | `boolean` | `true` | |
+| `closeOnEscape` | `boolean` | `true` | |
+| `width` / `height` | `string \| number` | `min(95vw,500px)` / `min(90vh,750px)` | any valid CSS size |
+| `maxWidth` / `maxHeight` | `string \| number` | `500px` / `750px` | |
+| `className` / `overlayClassName` / `iframeClassName` | `string` | — | |
+| `theme` | `"light" \| "dark" \| "auto"` | `"light"` | |
+| `zIndex` | `number` | — | |
+| `allow` | `string` | `"payment *"` | iframe `allow` attribute |
+| `sandbox` | `string` | unset | iframe `sandbox` attribute — see note below |
+| `loadingComponent` / `errorComponent` | `ReactNode` \| function | built-in views | |
+| `allowInsecureHttp` | `boolean` | `false` | dev-only override for non-HTTPS URLs |
+
+`sandbox` is left unset by default because an overly restrictive sandbox (e.g. missing `allow-forms` or `allow-popups` for a bank redirect) can silently break a gateway's checkout flow. Only set it if you've confirmed your gateway's checkout page works within the restrictions you choose.
+
+All exported types (`CheckoutProps`, `CheckoutProvider`, `CheckoutProviderConfig`, `CheckoutError`, `CheckoutMessage`, `CheckoutTheme`) and the `validateCheckoutUrl` utility are available from the package root.
+
+## Accessibility
+
+- `role="dialog"` + `aria-modal="true"`, labeled by the title (or an `aria-label` fallback)
+- Focus moves into the modal on open, is trapped there with Tab/Shift+Tab, and returns to the previously focused element on close
+- Escape closes the modal (configurable)
+- Background scroll is locked while open and restored on close
+
+## SSR
+
+The package never touches `window`/`document` at module scope — only inside effects and event handlers — so importing it is safe under Next.js, Remix, or any other SSR framework. The modal itself renders via a portal and only mounts client-side.
+
+## Security notes
+
+- `checkoutUrl` is validated before it's ever placed in an iframe: it must parse as a URL, must not use `javascript:`/`data:`/`vbscript:`/`file:`/`blob:`, and must be HTTPS unless you explicitly pass `allowInsecureHttp` (intended for local development only).
+- Incoming `postMessage` events are checked against a provider's `allowedOrigins` before anything else happens. If a provider declares no allow-list and doesn't explicitly set `supportsPostMessage: true`, every message is dropped — an unconfigured provider is trusted with nothing by default.
+- No built-in provider ships a `messageHandler` that fabricates a "success" message — see [Payment success handling](#payment-success-handling--read-this).
+- Never put a payment gateway's secret/API key in frontend code. This package never asks for one.
+
+## Gateway research notes
+
+Verified from Hubtel's public API reference: their checkout-URL flow is redirect + server-webhook based (`callbackUrl`, `returnUrl`, `cancellationUrl` parameters on the checkout initiation endpoint). No documented `postMessage` protocol exists for a checkout URL embedded via a plain iframe (their separate `@hubteljs/checkout` SDK manages its own iframe and bridge internally — a different integration path from "embed a URL you already have").
+
+**Empirically checked (2026-09-11)** against a live `pay.hubtel.com` checkout link: the response carries no `X-Frame-Options` header and its `Content-Security-Policy` has no `frame-ancestors` directive, so nothing at the HTTP level blocks embedding it in an iframe. The initial HTML also shows no obvious frame-busting script. This is a live-server observation, not a documented commitment from Hubtel — the checkout app is a client-rendered SPA (Nuxt) and its bundled JS wasn't fully audited for frame-busting, and Hubtel could add blocking headers at any time without notice. Treat iframe embedding of Hubtel's checkout as "currently unblocked," not "officially supported."
+
+Moolre's and PaySwitch's public documentation did not yield a confirmable `postMessage` protocol, `X-Frame-Options`/CSP frame policy, or iframe embedding guidance at the time this package was written. Rather than guess, `supportsPostMessage` is left `false` for all three built-in providers, and no provider-specific success/failure detection is implemented. If you have first-hand, documented knowledge of any of these gateways' embedding or messaging behavior, contributions with citations are very welcome.
+
+## Roadmap
+
+- `0.1.x` — core iframe modal (this release)
+- `0.2.x` — provider adapters and improved events, as gateway behavior gets verified
+- `0.3.x` — hook and `CheckoutButton` refinements
+- `1.0.0` — stable public API
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,253 @@
+import { ButtonHTMLAttributes } from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * A modal/iframe checkout for embedding a gateway-hosted checkout page.
+ *
+ * `checkoutUrl` must come from your backend's own integration with the
+ * payment provider's API — this component never talks to a gateway
+ * directly and never needs API keys. See the README for why frontend
+ * events here (including `onSuccess`) must not be treated as final proof
+ * of payment.
+ */
+export declare function Checkout({ open, checkoutUrl, provider, providerConfig: providerConfigOverrides, onClose, onOpen, onLoad, onError, onMessage, onSuccess, onFailure, onCancel, title, description, showCloseButton, closeOnOverlayClick, closeOnEscape, width, height, maxWidth, maxHeight, className, iframeClassName, overlayClassName, theme, zIndex, allow, sandbox, loadingComponent, errorComponent, allowInsecureHttp, id, children, }: CheckoutProps): JSX.Element | null;
+
+/**
+ * Convenience wrapper that owns its own `open` state: renders a trigger
+ * button and the {@link Checkout} modal together, for when you don't need
+ * to control the open state yourself.
+ */
+export declare function CheckoutButton({ children, buttonClassName, buttonProps, onClose, ...checkoutProps }: CheckoutButtonProps): JSX.Element;
+
+export declare interface CheckoutButtonProps extends Omit<CheckoutProps, "open"> {
+    children: ReactNode;
+    buttonClassName?: string;
+    buttonProps?: Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick" | "type" | "className">;
+}
+
+export declare interface CheckoutError {
+    code: CheckoutErrorCode;
+    message: string;
+    provider?: string;
+    originalError?: unknown;
+}
+
+export declare type CheckoutErrorCode = "INVALID_URL" | "IFRAME_LOAD_ERROR" | "PROVIDER_ERROR" | "MESSAGE_ERROR" | "UNKNOWN";
+
+/** A normalized, origin-validated message received from the checkout iframe. */
+export declare interface CheckoutMessage<TPayload = unknown> {
+    type: string;
+    provider?: string;
+    payload?: TPayload;
+    origin: string;
+    raw?: MessageEvent;
+}
+
+export declare interface CheckoutProps {
+    /** Controls whether the modal is rendered/visible. */
+    open: boolean;
+    /**
+     * The gateway-hosted checkout URL, obtained from your backend's
+     * integration with the payment provider's API. Never put secret API keys
+     * in the frontend to construct this URL yourself.
+     */
+    checkoutUrl: string;
+    /** Provider preset name, or an inline {@link CheckoutProviderConfig}. */
+    provider?: CheckoutProvider;
+    /** Overrides merged on top of the resolved provider preset. */
+    providerConfig?: Partial<CheckoutProviderConfig>;
+    onClose?: () => void;
+    onOpen?: () => void;
+    onLoad?: () => void;
+    onError?: (error: CheckoutError) => void;
+    /** Fires for every origin-validated, normalized message from the iframe. */
+    onMessage?: (message: CheckoutMessage) => void;
+    /**
+     * Fires only when a provider's `messageHandler` normalizes a message to
+     * type `"success"`. No built-in provider does this today — see
+     * `src/providers/*.ts`. Never treat this as final proof of payment;
+     * verify with your backend.
+     */
+    onSuccess?: (message: CheckoutMessage) => void;
+    /** Fires only when a provider normalizes a message to type `"failure"`. */
+    onFailure?: (message: CheckoutMessage) => void;
+    /** Fires only when a provider normalizes a message to type `"cancel"`. */
+    onCancel?: (message: CheckoutMessage) => void;
+    title?: string;
+    description?: string;
+    showCloseButton?: boolean;
+    closeOnOverlayClick?: boolean;
+    closeOnEscape?: boolean;
+    width?: string | number;
+    height?: string | number;
+    maxWidth?: string | number;
+    maxHeight?: string | number;
+    className?: string;
+    iframeClassName?: string;
+    overlayClassName?: string;
+    theme?: CheckoutTheme;
+    zIndex?: number;
+    /** Value for the iframe's `allow` attribute. Defaults to `"payment *"`. */
+    allow?: string;
+    /** Value for the iframe's `sandbox` attribute. Unset by default. */
+    sandbox?: string;
+    loadingComponent?: ReactNode;
+    errorComponent?: ReactNode | ((error: CheckoutError) => ReactNode);
+    /**
+     * Allow non-HTTPS checkout URLs. Intended for local development only —
+     * never enable this in production.
+     */
+    allowInsecureHttp?: boolean;
+    /** Accessible id used to associate the dialog with its title. */
+    id?: string;
+    children?: ReactNode;
+}
+
+/** A provider preset name, or a full inline provider configuration. */
+export declare type CheckoutProvider = CheckoutProviderName | CheckoutProviderConfig;
+
+/**
+ * Gateway-specific behavior. Built-in presets (hubtel/moolre/payswitch) fill
+ * this in with only what is actually documented by that gateway — see
+ * `src/providers/*.ts` for citations and known-unknowns.
+ */
+export declare interface CheckoutProviderConfig {
+    /** Identifier used in error/message payloads and default titles. */
+    name: string;
+    /**
+     * Origins allowed to send this provider's iframe `postMessage` events.
+     * When empty/undefined, incoming messages are ignored unless
+     * `supportsPostMessage` is explicitly true.
+     */
+    allowedOrigins?: string[];
+    defaultTitle?: string;
+    defaultWidth?: string | number;
+    defaultHeight?: string | number;
+    /**
+     * Whether this gateway has a documented postMessage protocol for a
+     * generically embedded checkout URL. Defaults to `false` for all built-in
+     * providers because none currently publish one — see provider source
+     * files. Do not flip this to `true` without a verified source.
+     */
+    supportsPostMessage?: boolean;
+    /**
+     * Normalizes a raw `MessageEvent` into a {@link CheckoutMessage}, or
+     * returns `null` to ignore it. Only called after origin validation.
+     */
+    messageHandler?: (event: MessageEvent) => CheckoutMessage | null;
+    /** Value for the iframe's `allow` attribute. */
+    iframeAllow?: string;
+    /** Value for the iframe's `sandbox` attribute, if any. */
+    iframeSandbox?: string;
+}
+
+/**
+ * Built-in provider identifiers. These are convenience presets only —
+ * `provider` also accepts a full {@link CheckoutProviderConfig} object for
+ * gateways that aren't built in.
+ */
+export declare type CheckoutProviderName = "hubtel" | "moolre" | "payswitch" | "custom";
+
+export declare type CheckoutTheme = "light" | "dark" | "auto";
+
+/**
+ * Fallback used for `provider="custom"` with no inline config, and as the
+ * base merged under any user-supplied {@link CheckoutProviderConfig}.
+ * Intentionally trusts nothing by default: no allowed origins and
+ * `supportsPostMessage: false`, so postMessage events are ignored unless the
+ * developer explicitly configures otherwise.
+ */
+export declare const customProviderDefaults: CheckoutProviderConfig;
+
+/**
+ * Hubtel — Online Checkout.
+ *
+ * Verified (from Hubtel's public API reference for the checkout-URL
+ * initiation endpoint): the checkout URL flow is redirect + server webhook
+ * based. The merchant backend calls Hubtel's initiate endpoint with a
+ * `callbackUrl` (server-to-server webhook) and a `returnUrl` /
+ * `cancellationUrl` (browser redirect targets), then sends the customer to
+ * the resulting checkout URL.
+ *
+ * UNVERIFIED: Hubtel's public docs do not document a `window.postMessage`
+ * protocol for a checkout URL embedded via a plain iframe (as opposed to
+ * their separate `@hubteljs/checkout` SDK, which manages its own iframe and
+ * bridge internally and is a different integration path from "embed a URL
+ * you already have"). `supportsPostMessage` is therefore left `false` here
+ * — do not flip it on without a citation. Rely on `returnUrl`/`callbackUrl`
+ * plus backend verification instead of any frontend "success" signal.
+ */
+export declare const hubtelProvider: CheckoutProviderConfig;
+
+/**
+ * Moolre — Checkout / Collections.
+ *
+ * UNVERIFIED: Moolre's public API docs (docs.moolre.com) were not
+ * accessible as static, readable content at the time this adapter was
+ * written, so no `postMessage` protocol, allowed origins, or iframe
+ * embedding policy could be confirmed. `supportsPostMessage` is left
+ * `false` and no `messageHandler` is provided — do not assume behavior that
+ * hasn't been verified against Moolre's own documentation. Rely on the
+ * redirect/callback URLs you configure server-side plus backend
+ * verification instead of any frontend "success" signal.
+ */
+export declare const moolreProvider: CheckoutProviderConfig;
+
+export declare type OpenCheckoutOptions = Omit<CheckoutProps, "open">;
+
+/**
+ * PaySwitch — PayLink / hosted checkout.
+ *
+ * UNVERIFIED: PaySwitch's public docs describe PayLink (payment links/QR)
+ * and the TheTeller processing API, but no `postMessage` protocol, allowed
+ * origins, or iframe embedding policy for a generically embedded checkout
+ * URL could be confirmed from accessible documentation. `supportsPostMessage`
+ * is left `false` — do not assume behavior that hasn't been verified. Rely
+ * on the redirect/callback URLs you configure server-side plus backend
+ * verification instead of any frontend "success" signal.
+ */
+export declare const payswitchProvider: CheckoutProviderConfig;
+
+/**
+ * Resolves the `provider` + `providerConfig` props into one concrete
+ * {@link CheckoutProviderConfig}. Accepts either a built-in preset name or
+ * an inline config object (for gateways that aren't built in), and merges
+ * any `providerConfig` overrides on top.
+ */
+export declare function resolveProviderConfig(provider: CheckoutProvider | undefined, overrides?: Partial<CheckoutProviderConfig>): CheckoutProviderConfig;
+
+export declare interface UrlValidationOptions {
+    /** Allow `http:` URLs. Intended for local development only. */
+    allowInsecureHttp?: boolean;
+}
+
+export declare interface UrlValidationResult {
+    valid: boolean;
+    reason?: string;
+}
+
+/**
+ * Imperative alternative to rendering `<Checkout open={...} />` yourself.
+ * Keeps the simple `<Checkout />` component as the primary API — this is an
+ * optional convenience for call-site-driven flows (e.g. "Pay Now" inside a
+ * list where mounting a modal per row would be wasteful).
+ */
+export declare function useCheckout(defaultOptions?: Partial<OpenCheckoutOptions>): UseCheckoutResult;
+
+export declare interface UseCheckoutResult {
+    /** Opens the checkout modal with the given options. */
+    openCheckout: (options: OpenCheckoutOptions) => void;
+    closeCheckout: () => void;
+    isOpen: boolean;
+    /** Render this once, wherever the modal should live in the tree. */
+    CheckoutModal: () => JSX.Element | null;
+}
+
+/**
+ * Validates a gateway checkout URL before it is ever placed in an iframe's
+ * `src`. Rejects non-URLs, script-injection protocols, and (by default)
+ * plain `http:` URLs.
+ */
+export declare function validateCheckoutUrl(url: string, options?: UrlValidationOptions): UrlValidationResult;
+
+export { }

package/dist/index.js

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=require("react/jsx-runtime"),n=require("react"),me=require("react-dom"),C={name:"hubtel",defaultTitle:"Complete Payment",supportsPostMessage:!1,iframeAllow:"payment *"},F={name:"moolre",defaultTitle:"Complete Payment",supportsPostMessage:!1,iframeAllow:"payment *"},K={name:"payswitch",defaultTitle:"Complete Payment",supportsPostMessage:!1,iframeAllow:"payment *"},x={name:"custom",defaultTitle:"Complete Payment",supportsPostMessage:!1},ye={hubtel:C,moolre:F,payswitch:K,custom:x};function V(e,o){let t;return e?typeof e=="string"?t=ye[e]??{...x,name:e}:t={...x,...e}:t=x,o?{...t,...o}:t}const pe=new Set(["javascript:","data:","vbscript:","file:","blob:"]);function G(e,o={}){if(!e||typeof e!="string")return{valid:!1,reason:"A checkoutUrl is required."};let t;try{t=new URL(e)}catch{return{valid:!1,reason:`"${e}" is not a valid URL.`}}return pe.has(t.protocol)?{valid:!1,reason:`Unsafe URL protocol "${t.protocol}" is not allowed.`}:t.protocol!=="https:"&&t.protocol!=="http:"?{valid:!1,reason:`Unsupported URL protocol "${t.protocol}".`}:t.protocol==="http:"&&!o.allowInsecureHttp?{valid:!1,reason:"checkoutUrl must use HTTPS. Pass allowInsecureHttp to override for local development only."}:{valid:!0}}function ve(e,o){return!o||o.length===0?!1:o.some(t=>{try{return new URL(t).origin===e}catch{return t===e}})}function ke(e,o){return function(r){if(!!e.allowedOrigins&&e.allowedOrigins.length>0){if(!ve(r.origin,e.allowedOrigins))return}else if(!e.supportsPostMessage)return;let c=null;if(e.messageHandler)try{c=e.messageHandler(r)}catch{return}else if(r.data&&typeof r.data=="object"){const s=r.data;c={type:typeof s.type=="string"?s.type:"message",provider:e.name,payload:r.data,origin:r.origin}}c&&o({...c,origin:r.origin,raw:r})}}const H=typeof window<"u"&&typeof document<"u";function N(...e){return e.filter(Boolean).join(" ")}let L=0,X="",J="";function be(){if(H){if(L===0){const e=window.innerWidth-document.documentElement.clientWidth;X=document.body.style.overflow,J=document.body.style.paddingRight,document.body.style.overflow="hidden",e>0&&(document.body.style.paddingRight=`${e}px`)}L+=1}}function ge(){H&&(L=Math.max(0,L-1),L===0&&(document.body.style.overflow=X,document.body.style.paddingRight=J))}const we=["a[href]","button:not([disabled])","textarea:not([disabled])","input:not([disabled])","select:not([disabled])","iframe",'[tabindex]:not([tabindex="-1"])'].join(",");function z(e){return Array.from(e.querySelectorAll(we))}function xe(e){return function(t){if(t.key!=="Tab")return;const r=z(e);if(r.length===0){t.preventDefault();return}const i=r[0],c=r[r.length-1],s=document.activeElement;t.shiftKey?(s===i||!e.contains(s))&&(t.preventDefault(),c.focus()):(s===c||!e.contains(s))&&(t.preventDefault(),i.focus())}}function q(e){return typeof e=="number"?`${e}px`:e}function Le({id:e,title:o,description:t,showCloseButton:r,closeOnOverlayClick:i,closeOnEscape:c,onClose:s,width:l,height:f,maxWidth:u,maxHeight:p,className:h,overlayClassName:b,theme:g,zIndex:R,children:I}){const w=n.useRef(null),j=n.useRef(null);n.useEffect(()=>{be(),j.current=document.activeElement;const d=w.current;return d&&(z(d)[0]??d).focus(),()=>{var m,T;ge(),(T=(m=j.current)==null?void 0:m.focus)==null||T.call(m)}},[]),n.useEffect(()=>{if(!c)return;function d(m){m.key==="Escape"&&(m.stopPropagation(),s==null||s())}return document.addEventListener("keydown",d),()=>document.removeEventListener("keydown",d)},[c,s]);function U(d){d.key==="Tab"&&w.current&&xe(w.current)(d.nativeEvent)}function M(d){i&&d.target===d.currentTarget&&(s==null||s())}const E=`${e}-title`,P=t?`${e}-description`:void 0;return a.jsx("div",{className:"vq-checkout-root","data-theme":g,children:a.jsx("div",{className:N("vq-checkout-overlay",b),onMouseDown:M,style:R!==void 0?{zIndex:R}:void 0,children:a.jsxs("div",{ref:w,id:e,role:"dialog","aria-modal":"true","aria-labelledby":o?E:void 0,"aria-label":o?void 0:"Checkout","aria-describedby":P,className:N("vq-checkout-modal",h),style:{width:q(l),height:q(f),maxWidth:q(u),maxHeight:q(p)},tabIndex:-1,onKeyDown:U,children:[(o||t||r)&&a.jsxs("div",{className:"vq-checkout-header",children:[a.jsxs("div",{className:"vq-checkout-heading",children:[o&&a.jsx("h2",{id:E,className:"vq-checkout-title",children:o}),t&&a.jsx("p",{id:P,className:"vq-checkout-description",children:t})]}),r&&a.jsx("button",{type:"button",className:"vq-checkout-close","aria-label":"Close checkout",onClick:()=>s==null?void 0:s(),children:a.jsx("svg",{width:"16",height:"16",viewBox:"0 0 16 16",fill:"none","aria-hidden":"true",children:a.jsx("path",{d:"M2 2L14 14M14 2L2 14",stroke:"currentColor",strokeWidth:"1.6",strokeLinecap:"round"})})})]}),a.jsx("div",{className:"vq-checkout-body",children:I})]})})})}function Re({src:e,title:o,className:t,allow:r,sandbox:i,hidden:c,onLoad:s,onError:l}){const f=n.useRef(null),u=n.useRef(s),p=n.useRef(l);return u.current=s,p.current=l,n.useEffect(()=>{const h=f.current;if(!h)return;const b=()=>u.current(),g=()=>p.current();return h.addEventListener("load",b),h.addEventListener("error",g),()=>{h.removeEventListener("load",b),h.removeEventListener("error",g)}},[e]),a.jsx("iframe",{ref:f,src:e,title:o,className:N("vq-checkout-iframe",t),allow:r,sandbox:i,style:c?{position:"absolute",width:0,height:0,opacity:0}:void 0})}function je(){return a.jsxs("div",{className:"vq-checkout-state",role:"status","aria-live":"polite",children:[a.jsx("div",{className:"vq-checkout-spinner","aria-hidden":"true"}),a.jsx("span",{children:"Loading secure checkout..."})]})}function Ee({error:e}){return a.jsxs("div",{className:"vq-checkout-state",role:"alert",children:[a.jsx("div",{className:"vq-checkout-error-icon","aria-hidden":"true",children:"!"}),a.jsx("p",{className:"vq-checkout-error-message",children:e.message})]})}const Pe="min(95vw, 500px)",Te="min(90vh, 750px)",Ae="500px",De="750px",qe="payment *";function B({open:e,checkoutUrl:o,provider:t,providerConfig:r,onClose:i,onOpen:c,onLoad:s,onError:l,onMessage:f,onSuccess:u,onFailure:p,onCancel:h,title:b,description:g,showCloseButton:R=!0,closeOnOverlayClick:I=!0,closeOnEscape:w=!0,width:j=Pe,height:U=Te,maxWidth:M=Ae,maxHeight:E=De,className:P,iframeClassName:d,overlayClassName:m,theme:T="light",zIndex:Q,allow:Y,sandbox:Z,loadingComponent:ee,errorComponent:S,allowInsecureHttp:W,id:te,children:re}){const se=n.useId(),oe=te??`vq-checkout-${se}`,[ne,ae]=n.useState(!1),[A,D]=n.useState("loading"),[_,O]=n.useState(null),$=n.useRef(!1),v=n.useMemo(()=>V(t,r),[t,JSON.stringify(r??{})]);n.useEffect(()=>{ae(!0)},[]),n.useEffect(()=>{e&&!$.current&&(c==null||c()),$.current=e},[e]),n.useEffect(()=>{if(!e)return;const k=G(o,{allowInsecureHttp:W});if(!k.valid){const y={code:"INVALID_URL",message:k.reason??"The provided checkoutUrl is invalid.",provider:v.name};D("error"),O(y),l==null||l(y);return}D("loading"),O(null)},[e,o,W]),n.useEffect(()=>{if(!e||!H)return;const k=ke(v,y=>{f==null||f(y),y.type==="success"?u==null||u(y):y.type==="failure"?p==null||p(y):y.type==="cancel"&&(h==null||h(y))});return window.addEventListener("message",k),()=>window.removeEventListener("message",k)},[e,v,f,u,p,h]);const ce=n.useCallback(()=>{D("loaded"),s==null||s()},[s]),ie=n.useCallback(()=>{const k={code:"IFRAME_LOAD_ERROR",message:"The checkout page could not be loaded.",provider:v.name};D("error"),O(k),l==null||l(k)},[l,v.name]),le=n.useCallback(()=>{i==null||i()},[i]);if(!e||!ne)return null;const ue=b??v.defaultTitle??"Checkout",de=Y??v.iframeAllow??qe,fe=Z??v.iframeSandbox,he=a.jsxs(Le,{id:oe,title:b??v.defaultTitle,description:g,showCloseButton:R,closeOnOverlayClick:I,closeOnEscape:w,onClose:le,width:j,height:U,maxWidth:M,maxHeight:E,className:P,overlayClassName:m,theme:T,zIndex:Q,children:[A==="loading"&&(ee??a.jsx(je,{})),A==="error"&&_&&(typeof S=="function"?S(_):S??a.jsx(Ee,{error:_})),A!=="error"&&a.jsx(Re,{src:o,title:ue,className:d,allow:de,sandbox:fe,hidden:A==="loading",onLoad:ce,onError:ie}),re]});return me.createPortal(he,document.body)}function Ne({children:e,buttonClassName:o,buttonProps:t,onClose:r,...i}){const[c,s]=n.useState(!1);return a.jsxs(a.Fragment,{children:[a.jsx("button",{type:"button",className:N("vq-checkout-trigger",o),onClick:()=>s(!0),...t,children:e}),a.jsx(B,{...i,open:c,onClose:()=>{s(!1),r==null||r()}})]})}function Ie(e){const[o,t]=n.useState(!1),[r,i]=n.useState(null),c=n.useRef(e);c.current=e;const s=n.useCallback(u=>{i({...c.current,...u}),t(!0)},[]),l=n.useCallback(()=>t(!1),[]),f=n.useCallback(()=>r?a.jsx(B,{...r,open:o,onClose:()=>{var u;(u=r.onClose)==null||u.call(r),t(!1)}}):null,[r,o]);return n.useMemo(()=>({openCheckout:s,closeCheckout:l,isOpen:o,CheckoutModal:f}),[s,l,o,f])}exports.Checkout=B;exports.CheckoutButton=Ne;exports.customProviderDefaults=x;exports.hubtelProvider=C;exports.moolreProvider=F;exports.payswitchProvider=K;exports.resolveProviderConfig=V;exports.useCheckout=Ie;exports.validateCheckoutUrl=G;
+//# sourceMappingURL=index.js.map