pepay-streams-sdk 0.1.0

package/src/react/index.ts

@@ -0,0 +1,498 @@
+/**
+ * React Integration Helpers
+ *
+ * Provides React-friendly patterns for using the SDK:
+ * - Context provider
+ * - Hooks for common operations
+ * - Type-safe query helpers
+ */
+
+// Note: This module provides patterns and helpers, not actual React hooks,
+// since we want to avoid React as a hard dependency.
+
+import type { Address } from 'viem';
+import type { PepayStreamsConfig } from '../types';
+import { PepayStreamsClient, PepayStreamsClientWithSigner } from '../client';
+
+/**
+ * SDK context value type for React context
+ */
+export interface PepayStreamsContextValue {
+  /** SDK client instance */
+  client: PepayStreamsClient | PepayStreamsClientWithSigner | null;
+  /** Whether the client has a signer */
+  isConnected: boolean;
+  /** Connected wallet address */
+  address: Address | null;
+  /** Chain ID */
+  chainId: number;
+  /** Diamond contract address */
+  diamondAddress: Address;
+}
+
+/**
+ * Configuration for creating SDK context
+ */
+export interface CreateContextConfig extends PepayStreamsConfig {
+  /** Auto-connect on mount */
+  autoConnect?: boolean;
+}
+
+/**
+ * Helper to create SDK client configuration from environment
+ */
+export function getConfigFromEnv(): Partial<PepayStreamsConfig> {
+  if (typeof process === 'undefined') {
+    return {};
+  }
+
+  const config: Partial<PepayStreamsConfig> = {
+    chainId: Number(
+      process.env.NEXT_PUBLIC_CHAIN_ID ?? process.env.CHAIN_ID ?? '1'
+    ),
+  };
+
+  const rpcUrl = process.env.NEXT_PUBLIC_RPC_URL ?? process.env.RPC_URL;
+  if (rpcUrl) {
+    config.rpcUrl = rpcUrl;
+  }
+
+  const diamondAddress = process.env.NEXT_PUBLIC_DIAMOND_ADDRESS ??
+    process.env.DIAMOND_ADDRESS;
+  if (diamondAddress) {
+    config.diamondAddress = diamondAddress as Address;
+  }
+
+  const apiBaseUrl = process.env.NEXT_PUBLIC_API_URL ?? process.env.API_URL;
+  if (apiBaseUrl) {
+    config.apiBaseUrl = apiBaseUrl;
+  }
+
+  return config;
+}
+
+/**
+ * Example React context creation pattern
+ *
+ * @example
+ * ```tsx
+ * // contexts/PepayStreams.tsx
+ * import { createContext, useContext, useState, useEffect } from 'react';
+ * import { PepayStreamsClient, PepayStreamsClientWithSigner } from '@pepay-streams/sdk';
+ * import { useWalletClient, usePublicClient, useAccount } from 'wagmi';
+ *
+ * const PepayStreamsContext = createContext<PepayStreamsContextValue | null>(null);
+ *
+ * export function PepayStreamsProvider({ children, config }) {
+ *   const { address, isConnected } = useAccount();
+ *   const publicClient = usePublicClient();
+ *   const { data: walletClient } = useWalletClient();
+ *   const [client, setClient] = useState<PepayStreamsClient | null>(null);
+ *
+ *   useEffect(() => {
+ *     if (!publicClient) return;
+ *
+ *     if (walletClient && isConnected) {
+ *       setClient(new PepayStreamsClient(config).withSigner(walletClient));
+ *     } else {
+ *       setClient(new PepayStreamsClient(config));
+ *     }
+ *   }, [publicClient, walletClient, isConnected]);
+ *
+ *   return (
+ *     <PepayStreamsContext.Provider value={{ client, isConnected, address, ... }}>
+ *       {children}
+ *     </PepayStreamsContext.Provider>
+ *   );
+ * }
+ *
+ * export function usePepayStreams() {
+ *   const context = useContext(PepayStreamsContext);
+ *   if (!context) throw new Error('Must be used within PepayStreamsProvider');
+ *   return context;
+ * }
+ * ```
+ */
+export const CONTEXT_EXAMPLE = `
+// Example usage with wagmi and React
+
+import { createContext, useContext, useState, useEffect, ReactNode } from 'react';
+import { PepayStreamsClient, PepayStreamsClientWithSigner, PepayStreamsConfig } from '@pepay-streams/sdk';
+import { useWalletClient, usePublicClient, useAccount, useChainId } from 'wagmi';
+
+interface PepayStreamsContextValue {
+  client: PepayStreamsClient | PepayStreamsClientWithSigner | null;
+  isConnected: boolean;
+  isLoading: boolean;
+}
+
+const PepayStreamsContext = createContext<PepayStreamsContextValue>({
+  client: null,
+  isConnected: false,
+  isLoading: true,
+});
+
+export function PepayStreamsProvider({
+  children,
+  config,
+}: {
+  children: ReactNode;
+  config: PepayStreamsConfig;
+}) {
+  const { isConnected } = useAccount();
+  const chainId = useChainId();
+  const { data: walletClient, isLoading: walletLoading } = useWalletClient();
+  const [client, setClient] = useState<PepayStreamsClient | null>(null);
+
+  useEffect(() => {
+    const newClient = new PepayStreamsClient({
+      ...config,
+      chainId,
+    });
+
+    if (walletClient && isConnected) {
+      setClient(newClient.withSigner(walletClient));
+    } else {
+      setClient(newClient);
+    }
+  }, [walletClient, isConnected, chainId, config]);
+
+  return (
+    <PepayStreamsContext.Provider
+      value={{
+        client,
+        isConnected,
+        isLoading: walletLoading,
+      }}
+    >
+      {children}
+    </PepayStreamsContext.Provider>
+  );
+}
+
+export function usePepayStreams() {
+  return useContext(PepayStreamsContext);
+}
+
+// Usage in components:
+function ClaimButton({ campaignId }: { campaignId: bigint }) {
+  const { client, isConnected } = usePepayStreams();
+  const [loading, setLoading] = useState(false);
+
+  const handleClaim = async () => {
+    if (!client || !isConnected) return;
+
+    setLoading(true);
+    try {
+      const result = await client.claims.claim({ campaignId });
+      await result.wait();
+      console.log('Claimed!');
+    } catch (error) {
+      console.error('Claim failed:', error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <button onClick={handleClaim} disabled={!isConnected || loading}>
+      {loading ? 'Claiming...' : 'Claim'}
+    </button>
+  );
+}
+`;
+
+/**
+ * Query key factories for react-query integration
+ *
+ * @example
+ * ```tsx
+ * import { useQuery } from '@tanstack/react-query';
+ * import { queryKeys, usePepayStreams } from '@pepay-streams/sdk/react';
+ *
+ * function CampaignDetails({ id }) {
+ *   const { client } = usePepayStreams();
+ *
+ *   const { data: campaign, isLoading } = useQuery({
+ *     queryKey: queryKeys.campaign(id),
+ *     queryFn: () => client.campaigns.getCampaign(BigInt(id)),
+ *     enabled: !!client,
+ *   });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   return <div>{campaign?.name}</div>;
+ * }
+ * ```
+ */
+export const queryKeys = {
+  // Campaigns
+  campaigns: (params?: Record<string, unknown>) =>
+    ['pepay', 'campaigns', params] as const,
+  campaign: (id: string | bigint) => ['pepay', 'campaign', String(id)] as const,
+  campaignRecipients: (id: string | bigint, page?: number) =>
+    ['pepay', 'campaign', String(id), 'recipients', page] as const,
+  campaignActivity: (id: string | bigint, page?: number) =>
+    ['pepay', 'campaign', String(id), 'activity', page] as const,
+
+  // Claims
+  dueAmount: (campaignId: bigint, address: Address) =>
+    ['pepay', 'dueAmount', String(campaignId), address] as const,
+  recipientStatus: (campaignId: bigint, address: Address) =>
+    ['pepay', 'recipientStatus', String(campaignId), address] as const,
+
+  // Staking
+  stakingPools: (params?: Record<string, unknown>) =>
+    ['pepay', 'staking', 'pools', params] as const,
+  stakingPool: (id: string | bigint) =>
+    ['pepay', 'staking', 'pool', String(id)] as const,
+  userStake: (poolId: bigint, address: Address) =>
+    ['pepay', 'staking', 'userStake', String(poolId), address] as const,
+  pendingRewards: (poolId: bigint, address: Address) =>
+    ['pepay', 'staking', 'pendingRewards', String(poolId), address] as const,
+
+  // Marketplace
+  orders: (params?: Record<string, unknown>) =>
+    ['pepay', 'marketplace', 'orders', params] as const,
+  order: (id: string | bigint) =>
+    ['pepay', 'marketplace', 'order', String(id)] as const,
+  orderQuote: (id: string | bigint) =>
+    ['pepay', 'marketplace', 'order', String(id), 'quote'] as const,
+
+  // Wallet
+  walletActivity: (address: Address) =>
+    ['pepay', 'wallet', address, 'activity'] as const,
+  walletPositions: (address: Address) =>
+    ['pepay', 'wallet', address, 'positions'] as const,
+  walletClaims: (address: Address, page?: number) =>
+    ['pepay', 'wallet', address, 'claims', page] as const,
+
+  // Tokens
+  tokenBalance: (token: Address, address: Address) =>
+    ['pepay', 'token', token, 'balance', address] as const,
+  tokenAllowance: (token: Address, owner: Address, spender: Address) =>
+    ['pepay', 'token', token, 'allowance', owner, spender] as const,
+  tokenInfo: (token: Address) => ['pepay', 'token', token, 'info'] as const,
+
+  // Automation
+  autoWithdrawStatus: (campaignId: bigint) =>
+    ['pepay', 'automation', 'autoWithdraw', String(campaignId)] as const,
+  autoReleaseStatus: (campaignId: bigint) =>
+    ['pepay', 'automation', 'autoRelease', String(campaignId)] as const,
+};
+
+/**
+ * Mutation key factories for react-query
+ */
+export const mutationKeys = {
+  claim: (campaignId: bigint) =>
+    ['pepay', 'mutation', 'claim', String(campaignId)] as const,
+  claimBatch: () => ['pepay', 'mutation', 'claimBatch'] as const,
+  stake: (poolId: bigint) =>
+    ['pepay', 'mutation', 'stake', String(poolId)] as const,
+  unstake: (poolId: bigint) =>
+    ['pepay', 'mutation', 'unstake', String(poolId)] as const,
+  fillOrder: (orderId: bigint) =>
+    ['pepay', 'mutation', 'fillOrder', String(orderId)] as const,
+  cancelOrder: (orderId: bigint) =>
+    ['pepay', 'mutation', 'cancelOrder', String(orderId)] as const,
+  approve: (token: Address) =>
+    ['pepay', 'mutation', 'approve', token] as const,
+};
+
+/**
+ * Example hook patterns for common operations
+ */
+export const HOOK_EXAMPLES = `
+// Custom hooks for common operations
+
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { usePepayStreams, queryKeys, mutationKeys } from '@pepay-streams/sdk/react';
+import { parseEther } from 'viem';
+
+// Hook: Get campaign with due amount
+export function useCampaignWithDue(campaignId: bigint, recipientAddress: Address) {
+  const { client } = usePepayStreams();
+
+  const campaign = useQuery({
+    queryKey: queryKeys.campaign(campaignId),
+    queryFn: () => client!.campaigns.getCampaign(campaignId),
+    enabled: !!client,
+  });
+
+  const dueAmount = useQuery({
+    queryKey: queryKeys.dueAmount(campaignId, recipientAddress),
+    queryFn: () => client!.claims.getDueAmount(campaignId, recipientAddress),
+    enabled: !!client && !!recipientAddress,
+    refetchInterval: 30000, // Refresh every 30s
+  });
+
+  return {
+    campaign: campaign.data,
+    dueAmount: dueAmount.data,
+    isLoading: campaign.isLoading || dueAmount.isLoading,
+  };
+}
+
+// Hook: Claim mutation with optimistic updates
+export function useClaim() {
+  const { client } = usePepayStreams();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({ campaignId }: { campaignId: bigint }) => {
+      const result = await client!.claims.claim({ campaignId });
+      return result.wait();
+    },
+    onSuccess: (_, { campaignId }) => {
+      // Invalidate related queries
+      queryClient.invalidateQueries({ queryKey: queryKeys.campaign(campaignId) });
+      queryClient.invalidateQueries({ queryKey: ['pepay', 'dueAmount', String(campaignId)] });
+    },
+  });
+}
+
+// Hook: Stake with approval check
+export function useStake() {
+  const { client } = usePepayStreams();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({
+      poolId,
+      amount,
+      stakeToken,
+    }: {
+      poolId: bigint;
+      amount: bigint;
+      stakeToken: Address;
+    }) => {
+      // Check and approve if needed
+      const approval = await (client as PepayStreamsClientWithSigner).ensureAllowance(stakeToken, amount);
+      if (approval) {
+        await approval.wait();
+      }
+
+      // Stake
+      const result = await client!.staking.stake(poolId, amount);
+      return result.wait();
+    },
+    onSuccess: (_, { poolId }) => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.stakingPool(poolId) });
+      queryClient.invalidateQueries({ queryKey: ['pepay', 'staking', 'userStake', String(poolId)] });
+    },
+  });
+}
+
+// Hook: Fill order with price display
+export function useOrderWithQuote(orderId: bigint) {
+  const { client } = usePepayStreams();
+
+  const order = useQuery({
+    queryKey: queryKeys.order(orderId),
+    queryFn: () => client!.marketplace.getOrder(orderId),
+    enabled: !!client,
+  });
+
+  const quote = useQuery({
+    queryKey: queryKeys.orderQuote(orderId),
+    queryFn: () => client!.marketplace.getQuote(orderId),
+    enabled: !!client && order.data?.status === 'open',
+    refetchInterval: 10000, // Refresh quote every 10s
+  });
+
+  return {
+    order: order.data,
+    quote: quote.data,
+    isLoading: order.isLoading || quote.isLoading,
+    canFill: quote.data?.isValid ?? false,
+  };
+}
+`;
+
+/**
+ * Format helpers for display
+ */
+export const formatters = {
+  /**
+   * Format token amount with decimals
+   */
+  formatTokenAmount(amount: bigint, decimals = 18, maxDecimals = 4): string {
+    const divisor = BigInt(10 ** decimals);
+    const integerPart = amount / divisor;
+    const fractionalPart = amount % divisor;
+
+    const fractionalStr = fractionalPart.toString().padStart(decimals, '0');
+    const trimmedFractional = fractionalStr.slice(0, maxDecimals).replace(/0+$/, '');
+
+    if (trimmedFractional) {
+      return `${integerPart}.${trimmedFractional}`;
+    }
+    return integerPart.toString();
+  },
+
+  /**
+   * Format USD amount
+   */
+  formatUsd(amount: number | string): string {
+    const num = typeof amount === 'string' ? parseFloat(amount) : amount;
+    return new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: 'USD',
+      minimumFractionDigits: 2,
+      maximumFractionDigits: 2,
+    }).format(num);
+  },
+
+  /**
+   * Format percentage
+   */
+  formatPercent(value: number, decimals = 2): string {
+    return `${value.toFixed(decimals)}%`;
+  },
+
+  /**
+   * Format timestamp to date string
+   */
+  formatDate(timestamp: number): string {
+    return new Date(timestamp * 1000).toLocaleDateString();
+  },
+
+  /**
+   * Format timestamp to relative time
+   */
+  formatRelativeTime(timestamp: number): string {
+    const now = Math.floor(Date.now() / 1000);
+    const diff = timestamp - now;
+
+    if (diff < 0) {
+      const absDiff = Math.abs(diff);
+      if (absDiff < 60) return 'just now';
+      if (absDiff < 3600) return `${Math.floor(absDiff / 60)}m ago`;
+      if (absDiff < 86400) return `${Math.floor(absDiff / 3600)}h ago`;
+      return `${Math.floor(absDiff / 86400)}d ago`;
+    }
+
+    if (diff < 60) return 'in < 1m';
+    if (diff < 3600) return `in ${Math.floor(diff / 60)}m`;
+    if (diff < 86400) return `in ${Math.floor(diff / 3600)}h`;
+    return `in ${Math.floor(diff / 86400)}d`;
+  },
+
+  /**
+   * Format vesting progress
+   */
+  formatVestingProgress(claimed: bigint, allocated: bigint): string {
+    if (allocated === 0n) return '0%';
+    const progress = Number((claimed * 100n) / allocated);
+    return `${progress.toFixed(1)}%`;
+  },
+
+  /**
+   * Shorten address for display
+   */
+  shortenAddress(address: Address, chars = 4): string {
+    return `${address.slice(0, chars + 2)}...${address.slice(-chars)}`;
+  },
+};
+
+// Types are already exported as interfaces above