@bbuilders/djeon402-sdk-client 1.0.1

package/README.md

@@ -0,0 +1,355 @@
+# @bbuilders/djeon402/sdk-client
+
+Browser SDK for DJEON402 token with React hooks and Vue composables support.
+
+## Features
+
+- ✅ **React Hooks** - Ready-to-use hooks with wagmi integration
+- ✅ **Vue Composables** - Vue 3 Composition API support
+- ✅ **TypeScript** - Full type safety
+- ✅ **Wallet Integration** - MetaMask, WalletConnect, etc.
+- ✅ **No Private Keys** - Secure wallet-based signing
+- ✅ **x402 Gasless** - Sign gasless transfer authorizations
+
+## Installation
+
+```bash
+# npm
+npm install @bbuilders/djeon402/sdk-client viem wagmi
+
+# pnpm
+pnpm add @bbuilders/djeon402/sdk-client viem wagmi
+
+# yarn
+yarn add @bbuilders/djeon402/sdk-client viem wagmi
+```
+
+## Quick Start
+
+### React + wagmi
+
+#### 1. Setup Provider
+
+```tsx
+import { Djeon402Provider } from '@bbuilders/djeon402/sdk-client/react';
+import { WagmiProvider, createConfig, http } from 'wagmi';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+// Configuration constants
+const DJEON402_CONTRACT = '0x...';
+const KYC_REGISTRY = '0x....';
+const CHAIN_ID = 31337;
+
+const config = createConfig({
+  chains: [/* your chains */],
+  transports: {
+    /* your transports */
+  },
+});
+
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <WagmiProvider config={config}>
+      <QueryClientProvider client={queryClient}>
+        <Djeon402Provider
+          config={{
+            contractAddress: DJEON402_CONTRACT,
+            kycRegistryAddress: KYC_REGISTRY,
+            chainId: CHAIN_ID,
+          }}
+        >
+          <YourApp />
+        </Djeon402Provider>
+      </QueryClientProvider>
+    </WagmiProvider>
+  );
+}
+```
+
+#### 2. Use Hooks
+
+```tsx
+import { useAccount } from 'wagmi';
+import { useBalance, useTransfer } from '@bbuilders/djeon402/sdk-client/react';
+
+// Test account addresses
+const RECIPIENT_ADDRESS = '0x...';
+
+// Transfer amount constant
+const TRANSFER_AMOUNT = '100';
+
+function TokenDashboard() {
+  const { address } = useAccount();
+  const { data: balance, isLoading } = useBalance(address);
+  const { transfer, isLoading: isTransferring } = useTransfer();
+
+  const handleTransfer = async () => {
+    await transfer({
+      to: RECIPIENT_ADDRESS,
+      amount: TRANSFER_AMOUNT,
+    });
+  };
+
+  return (
+    <div>
+      <p>Balance: {balance?.balance}</p>
+      <button onClick={handleTransfer} disabled={isTransferring}>
+        Send {TRANSFER_AMOUNT} Tokens
+      </button>
+    </div>
+  );
+}
+```
+
+### Vue 3
+
+#### 1. Setup Provider
+
+```vue
+<script setup lang="ts">
+import { provideDjeon402 } from '@bbuilders/djeon402/sdk-client/vue';
+
+// Configuration constants
+const DJEON402_CONTRACT = '0x....';
+const KYC_REGISTRY = '0x....';
+const RPC_URL = 'http://localhost:8545';
+const CHAIN_ID = 31337;
+
+provideDjeon402({
+  contractAddress: DJEON402_CONTRACT,
+  kycRegistryAddress: KYC_REGISTRY,
+  chainId: CHAIN_ID,
+  rpcUrl: RPC_URL,
+});
+</script>
+
+<template>
+  <YourApp />
+</template>
+```
+
+#### 2. Use Composables
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import { useBalance, useTransfer } from '@bbuilders/djeon402/sdk-client/vue';
+import { useWalletClient } from '@wagmi/vue';
+
+// Test account addresses
+const RECIPIENT_ADDRESS = '0x.....';
+
+// Transfer amount constant
+const TRANSFER_AMOUNT = '100';
+
+const { data: walletClient } = useWalletClient();
+const address = computed(() => walletClient.value?.account?.address);
+
+const { data: balance, isLoading } = useBalance(address);
+const { transfer, isLoading: isTransferring } = useTransfer(walletClient);
+
+const handleTransfer = async () => {
+  await transfer(RECIPIENT_ADDRESS, TRANSFER_AMOUNT);
+};
+</script>
+
+<template>
+  <div>
+    <p>Balance: {{ balance?.balance }}</p>
+    <button @click="handleTransfer" :disabled="isTransferring">
+      Send {{ TRANSFER_AMOUNT }} Tokens
+    </button>
+  </div>
+</template>
+```
+
+### Vanilla JavaScript
+
+```typescript
+import { Djeon402ClientSDK } from '@bbuilders/djeon402/sdk-client';
+import { createWalletClient, custom } from 'viem';
+
+// Configuration constants
+const DJEON402_CONTRACT = '0x....';
+const RECIPIENT_ADDRESS = '0x....';
+const RPC_URL = 'http://localhost:8545';
+const CHAIN_ID = 31337;
+const TRANSFER_AMOUNT = '100';
+
+// Create SDK instance
+const sdk = new Djeon402ClientSDK({
+  contractAddress: DJEON402_CONTRACT,
+  chainId: CHAIN_ID,
+  rpcUrl: RPC_URL,
+});
+
+// Get token info
+const info = await sdk.token.getInfo();
+console.log(info);
+
+// Create wallet client from browser wallet (MetaMask)
+const walletClient = createWalletClient({
+  chain: sdk.getChain(),
+  transport: custom(window.ethereum),
+});
+
+// Transfer tokens
+const result = await sdk.token.transfer({
+  walletClient,
+  to: RECIPIENT_ADDRESS,
+  amount: TRANSFER_AMOUNT,
+});
+```
+
+## API Reference
+
+### React Hooks
+
+All hooks require `Djeon402Provider` to be set up in your app.
+
+- `useTokenInfo()` - Get token information
+- `useBalance(address)` - Get balance of an address
+- `useTransfer()` - Transfer tokens
+- `useApprove()` - Approve spending
+- `useX402Transfer()` - Sign gasless transfer authorization
+- `useX402Receive()` - Sign gasless receive authorization
+- `useKYCData(address)` - Get KYC data
+- `useIsBlacklisted(address)` - Check blacklist status
+
+### Vue Composables
+
+Same API as React hooks, compatible with Vue 3 reactivity.
+
+- `useTokenInfo()`, `useBalance()`, `useTransfer()`, `useApprove()`
+- `useX402Transfer(walletClient)` - Sign gasless transfer
+- `useX402Receive(walletClient)` - Sign gasless receive
+- `useKYCData()`, `useIsBlacklisted()`
+
+### Core SDK Modules
+
+- `sdk.token` - ERC-20 operations
+- `sdk.admin` - Admin functions
+- `sdk.kyc` - KYC management
+- `sdk.x402` - Gasless transfers (sign, execute, receive, cancel, fetchWithPayment)
+
+## Examples
+
+### Gasless Payment (x402)
+
+```tsx
+import { useX402Transfer } from '@bbuilders/djeon402/sdk-client/react';
+
+// Merchant configuration
+const MERCHANT_ADDRESS = '0xMerchantAddress...';
+const PAYMENT_AMOUNT = '99.99';
+
+function CheckoutButton() {
+  const { signTransfer } = useX402Transfer();
+
+  const handlePayment = async () => {
+    // User signs authorization (no gas needed!)
+    const authorization = await signTransfer({
+      to: MERCHANT_ADDRESS,
+      amount: PAYMENT_AMOUNT,
+    });
+
+    // Send to backend for execution
+    await fetch('/api/relay-payment', {
+      method: 'POST',
+      body: JSON.stringify({ authorization }),
+    });
+  };
+
+  return <button onClick={handlePayment}>Pay ${PAYMENT_AMOUNT}</button>;
+}
+```
+
+### Receive Authorization (Payee-Initiated)
+
+```tsx
+import { useX402Receive } from '@bbuilders/djeon402/sdk-client/react';
+
+function ReceiveButton() {
+  const { signReceive } = useX402Receive();
+
+  const handleReceive = async () => {
+    // Receiver signs to pull funds from sender
+    const authorization = await signReceive({
+      from: '0xSender...',
+      amount: '50',
+    });
+
+    // Send to backend for execution
+    await fetch('/api/relay/execute-receive', {
+      method: 'POST',
+      body: JSON.stringify({ authorization }),
+    });
+  };
+
+  return <button onClick={handleReceive}>Receive 50 Tokens</button>;
+}
+```
+
+### Auto-Handle 402 Payment Required
+
+```typescript
+import { Djeon402ClientSDK } from '@bbuilders/djeon402/sdk-client';
+
+const sdk = new Djeon402ClientSDK({ contractAddress: '0x...', chainId: 31337 });
+
+// Automatically handles HTTP 402 responses:
+// 1. Detects 402 + PAYMENT-REQUIRED header
+// 2. Signs transfer authorization with wallet
+// 3. Retries with PAYMENT-SIGNATURE header
+const response = await sdk.x402.fetchWithPayment(walletClient, '/api/content/article-1');
+```
+
+### Check KYC Before Transfer
+
+```tsx
+import { useAccount } from 'wagmi';
+import { useKYCData, useTransfer } from '@bbuilders/djeon402/sdk-client/react';
+
+// Transfer configuration
+const RECIPIENT_ADDRESS = '0xRecipientAddress...';
+const TRANSFER_AMOUNT = '1000';
+
+function SecureTransfer() {
+  const { address } = useAccount();
+  const { data: kyc } = useKYCData(address);
+  const { transfer } = useTransfer();
+
+  const handleTransfer = async () => {
+    if (!kyc?.isVerified) {
+      alert('Please complete KYC verification first');
+      return;
+    }
+
+    await transfer({
+      to: RECIPIENT_ADDRESS,
+      amount: TRANSFER_AMOUNT
+    });
+  };
+
+  return (
+    <div>
+      <p>KYC Status: {kyc?.levelName}</p>
+      <button onClick={handleTransfer}>Transfer</button>
+    </div>
+  );
+}
+```
+
+## Requirements
+
+- React >= 18.0.0 (for React hooks)
+- Vue >= 3.0.0 (for Vue composables)
+- wagmi ^2.0.0
+- viem ^2.0.0
+- @tanstack/react-query ^5.0.0 (for React)
+
+## License
+
+MIT