npm package: @kgen-protocol/crypto-pg-react-sdk
Description: React SDK for integrating the KGEN Crypto Payment Gateway (Crypto PG) into your dapps and products.
Latest version: 0.0.4

## @kgen-protocol/crypto-pg-react-sdk

React SDK for integrating the KGEN Crypto Payment Gateway (Crypto PG) into your dapps and products.

It gives you:

- **Iframe-based checkout** overlay
- **Multi-chain wallet providers** (EVM, Solana, Aptos)
- **Hooks** for sending/swap transactions via the payment gateway

---

## Installation

Install from npm:

```bash
npm install @kgen-protocol/crypto-pg-react-sdk
# or
yarn add @kgen-protocol/crypto-pg-react-sdk
```

Peer deps you should already have in a React app:

- **react** / **react-dom**

---

## Quick start (iframe checkout)

The simplest integration is to open the hosted Crypto PG UI in an iframe overlay.

```tsx
import React from "react";
import iframeManager, {
  type IframeConfig,
} from "@kgen-protocol/crypto-pg-react-sdk";

const CheckoutButton: React.FC = () => {
  const handleClick = () => {
    const url = "https://your-crypto-pg-host-url"; // e.g. https://crypto-pg.example.com

    const config: IframeConfig = {
      invoiceId: "INVOICE_ID_FROM_BACKEND",
      senderAddress: "0xUserWalletAddressOrChainSpecificAddress",
      authToken: "JWT_OR_SESSION_TOKEN_FROM_BACKEND",
      // cookie?: "optional-cookie-string",
    };

    iframeManager.open(
      url,
      () => {
        // onClose
        console.log("Crypto PG closed");
      },
      config,
      (successData) => {
        // onSuccess
        console.log("Payment success:", successData);
      },
      (errorData) => {
        // onError
        console.error("Payment error:", errorData);
      }
    );
  };

  return <button onClick={handleClick}>Pay with Crypto PG</button>;
};

export default CheckoutButton;
```

This:

- Creates a full-screen modal overlay.
- Loads your hosted Crypto PG UI in an iframe.
- Sends the `IframeConfig` (invoice, sender, auth token) into the iframe.
- Listens to success / error / close events from the iframe.

---

## Wallet provider setup

If you want to use the hooks directly (for advanced flows), you can also wrap your app in the SDK `WalletProviders` component instead of letting the iframe manager create its own providers.

```tsx
import React from "react";
import ReactDOM from "react-dom/client";
import { WalletProviders } from "@kgen-protocol/crypto-pg-react-sdk";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <React.StrictMode>
    <WalletProviders>
      <App />
    </WalletProviders>
  </React.StrictMode>
);
```

`WalletProviders` wires up:

- EVM wallets via `wagmi` (MetaMask, injected, Coinbase Wallet, etc.).
- Solana wallets (Phantom, Coinbase).
- Aptos wallets (Petra, Nightly).
- React Query for async state.

> Note: The iframe-based `iframeManager.open` already wraps its own internal UI with `WalletProviders`, so you only need this at the app root if you want to use the hooks outside the iframe flow.

---

## Hooks

The SDK exposes a small set of hooks for working with wallets and transactions.

### Connections

From `src/index.ts` exports:

- `useEVMConnection`
- `useAptosConnection`
- `useSolanaConnection`

Example (EVM):

```tsx
import { useEVMConnection } from "@kgen-protocol/crypto-pg-react-sdk";

const ConnectEvmWallet: React.FC = () => {
  const { connect, disconnect, address, isConnected } = useEVMConnection();

  return (
    <div>
      {isConnected ? (
        <>
          <p>Connected: {address}</p>
          <button onClick={disconnect}>Disconnect</button>
        </>
      ) : (
        <button onClick={connect}>Connect EVM Wallet</button>
      )}
    </div>
  );
};
```

### Transactions & swaps

Exports (see `src/index.ts`):

- `useSendEvmTransaction`
- `useSendAptosTransaction`
- `useSwapEvmTransaction`
- `useSwapSolanaTransaction`

Example (send EVM tx):

```tsx
import { useSendEvmTransaction } from "@kgen-protocol/crypto-pg-react-sdk";

const SendPaymentButton: React.FC = () => {
  const { sendTransaction, isLoading, error } = useSendEvmTransaction();

  const handleSend = async () => {
    try {
      await sendTransaction({
        // shape depends on your backend / gateway integration
        to: "0xRecipientAddress",
        value: "0.01", // ETH/chain native amount as string
        // ...any other fields your implementation expects
      });
      alert("Transaction sent!");
    } catch (err) {
      console.error(err);
    }
  };

  return (
    <button onClick={handleSend} disabled={isLoading}>
      {isLoading ? "Sending..." : "Send Crypto Payment"}
      {error && <span style={{ color: "red" }}>{String(error)}</span>}
    </button>
  );
};
```

Adjust the payload shape to match your actual hook implementation / backend schema.

---

## TypeScript

The package ships TypeScript types via:

- `"types": "dist/index.d.ts"`
- `IframeConfig` and `UnsignedEvmTransactionPayload` types are exported from the package entry.

Example:

```ts
import type {
  IframeConfig,
  UnsignedEvmTransactionPayload,
} from "@kgen-protocol/crypto-pg-react-sdk";
```

---

## Environment / framework notes

- The SDK is designed for **React 18+** (`react` / `react-dom` as peer deps).
- Internally uses `wagmi` + `@tanstack/react-query` + Solana/Aptos wallet adapters.
- Works in **Next.js** or **Vite** apps as long as components using the SDK are client-side.