pepay-streams-sdk 0.1.0

package/README.md

@@ -0,0 +1,405 @@
+# @pepay-streams/sdk
+
+TypeScript SDK for interacting with the Pepay Streams protocol - a production-grade EVM token distribution platform built on EIP-2535 Diamond architecture.
+
+## Features
+
+- **Token Distribution**: Create instant airdrops, vested airdrops, token locks, and vesting streams
+- **Staking Pools**: Create and manage fixed-duration staking pools with APY-based rewards
+- **P2P Marketplace**: Trade unvested positions through INSTANT, VESTED, and TRADABLE orders
+- **Automation**: Enable keeper-powered auto-withdraw and auto-release
+- **Meta-Transactions**: Support for gasless claims via EIP-712 signatures
+- **Type-Safe**: Full TypeScript support with comprehensive types
+
+## Installation
+
+```bash
+npm install @pepay-streams/sdk viem
+# or
+pnpm add @pepay-streams/sdk viem
+# or
+yarn add @pepay-streams/sdk viem
+```
+
+## Quick Start
+
+### Read-Only Client
+
+```typescript
+import { PepayStreamsClient } from '@pepay-streams/sdk';
+
+const client = new PepayStreamsClient({
+  rpcUrl: 'https://eth.llamarpc.com',
+  diamondAddress: '0x...',
+  chainId: 1,
+  apiBaseUrl: 'https://api.pepaystreams.com', // Optional
+});
+
+// Query campaigns
+const campaign = await client.campaigns.getCampaign(1n);
+console.log('Campaign:', campaign.name);
+
+// Check claimable amount
+const due = await client.claims.getDueAmount(1n, '0x...');
+console.log('Due amount:', due);
+```
+
+### Client with Signer (for transactions)
+
+```typescript
+import { PepayStreamsClient } from '@pepay-streams/sdk';
+import { createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { mainnet } from 'viem/chains';
+
+// From private key (Node.js/scripts)
+const client = PepayStreamsClient.fromPrivateKey({
+  rpcUrl: 'https://eth.llamarpc.com',
+  diamondAddress: '0x...',
+  chainId: 1,
+  privateKey: '0x...',
+});
+
+// Or attach a wallet client
+const walletClient = createWalletClient({
+  chain: mainnet,
+  transport: http(),
+  account: privateKeyToAccount('0x...'),
+});
+
+const clientWithSigner = new PepayStreamsClient({
+  rpcUrl: 'https://eth.llamarpc.com',
+  diamondAddress: '0x...',
+  chainId: 1,
+}).withSigner(walletClient);
+```
+
+### Browser Wallet
+
+```typescript
+import { PepayStreamsClient } from '@pepay-streams/sdk';
+
+// Connect to browser wallet (MetaMask, etc.)
+const client = await PepayStreamsClient.fromBrowserWallet({
+  diamondAddress: '0x...',
+  chainId: 1,
+});
+```
+
+## Campaign Operations
+
+### Create an Instant Airdrop
+
+```typescript
+import { parseEther } from 'viem';
+
+const result = await client.campaigns.createInstantAirdrop({
+  token: '0x...', // Token address
+  name: 'Community Airdrop',
+  recipients: [
+    { address: '0x...', amount: parseEther('100') },
+    { address: '0x...', amount: parseEther('50') },
+  ],
+});
+
+await result.wait();
+console.log('Created! Tx:', result.hash);
+```
+
+### Create a Vested Airdrop
+
+```typescript
+const result = await client.campaigns.createVestedAirdrop({
+  token: '0x...',
+  name: 'Team Vesting',
+  recipients: [
+    { address: '0x...', amount: parseEther('10000') },
+  ],
+  startTime: Math.floor(Date.now() / 1000), // Start now
+  duration: 365 * 24 * 60 * 60, // 1 year
+  cliffDuration: 90 * 24 * 60 * 60, // 3 month cliff
+  steps: 12, // Monthly releases
+});
+```
+
+### Create a Token Lock
+
+```typescript
+const result = await client.campaigns.createLock({
+  token: '0x...',
+  name: 'Liquidity Lock',
+  recipient: '0x...',
+  amount: parseEther('1000000'),
+  unlockTime: Math.floor(Date.now() / 1000) + 180 * 24 * 60 * 60, // 6 months
+});
+```
+
+### Create a Vesting Stream (Payment)
+
+```typescript
+const result = await client.campaigns.createVesting({
+  token: '0x...',
+  name: 'Salary Stream',
+  recipient: '0x...',
+  amount: parseEther('120000'),
+  startTime: Math.floor(Date.now() / 1000),
+  duration: 365 * 24 * 60 * 60, // 1 year
+  steps: 12, // Monthly
+  enableAutoWithdraw: true,
+  autoWithdrawFrequency: 30 * 24 * 60 * 60, // Monthly auto-claim
+});
+```
+
+## Claiming
+
+### Claim Tokens
+
+```typescript
+// Single claim
+const result = await client.claims.claim({ campaignId: 1n });
+await result.wait();
+
+// Batch claim from multiple campaigns
+const result = await client.claims.claimBatch({
+  campaignIds: [1n, 2n, 3n],
+});
+
+// Release a lock
+const result = await client.claims.releaseLock(campaignId);
+```
+
+### Check Claimable Amount
+
+```typescript
+const due = await client.claims.getDueAmount(campaignId, recipientAddress);
+console.log('Claimable:', formatEther(due));
+
+const status = await client.claims.getRecipientStatus(campaignId, recipientAddress);
+console.log('Allocated:', status.allocated);
+console.log('Claimed:', status.claimed);
+console.log('Due:', status.due);
+```
+
+### Meta-Transaction (Gasless) Claims
+
+```typescript
+// Recipient signs off-chain
+const { signature, nonce, deadline } = await client.claims.signClaimMessage(
+  campaignId,
+  Math.floor(Date.now() / 1000) + 3600 // 1 hour deadline
+);
+
+// Relayer submits the transaction
+const result = await relayerClient.claims.claimWithSig({
+  campaignId,
+  signature,
+  deadline,
+  signer: recipientAddress,
+});
+```
+
+## Staking
+
+### Create a Staking Pool
+
+```typescript
+const result = await client.staking.createPool({
+  stakeToken: '0x...', // Token users stake
+  rewardToken: '0x...', // Token users earn
+  rewardBudget: parseEther('100000'), // Total rewards
+  duration: 30 * 24 * 60 * 60, // 30 days
+  minStake: parseEther('100'),
+  maxStake: parseEther('10000'),
+});
+```
+
+### Stake Tokens
+
+```typescript
+// Approve first
+await client.approve(stakeToken, amount);
+
+// Then stake
+const result = await client.staking.stake(poolId, amount);
+await result.wait();
+```
+
+### Claim Rewards
+
+```typescript
+// Check pending rewards
+const pending = await client.staking.getPendingRewards(poolId, address);
+
+// Claim
+await client.staking.claimRewards(poolId);
+
+// Or unstake (automatically claims rewards)
+await client.staking.unstake(poolId, amount);
+```
+
+## Marketplace
+
+### Create an Order
+
+```typescript
+import { zeroAddress } from 'viem';
+
+// INSTANT order - immediate delivery
+await client.marketplace.createInstantOrder({
+  sellToken: '0x...',
+  sellAmount: parseEther('1000'),
+  payToken: zeroAddress, // Native ETH
+  pricePerToken: parseEther('0.001'),
+  expiryTTL: 7 * 24 * 60 * 60, // 7 days
+});
+
+// TRADABLE order - list unvested campaign position
+await client.marketplace.createTradableOrder({
+  campaignId: 10n,
+  pricePerToken: parseEther('0.05'),
+  payToken: zeroAddress,
+  expiryTTL: 30 * 24 * 60 * 60,
+});
+```
+
+### Fill an Order
+
+```typescript
+// Get quote
+const quote = await client.marketplace.getQuote(orderId);
+console.log('Total price:', quote.totalPrice);
+
+// Fill with native payment
+await client.marketplace.fillOrder(orderId, {
+  value: quote.totalPrice,
+});
+
+// Or with ERC20 (approve first)
+await client.approve(payToken, quote.totalPrice);
+await client.marketplace.fillOrder(orderId);
+```
+
+### Cancel an Order
+
+```typescript
+await client.marketplace.cancelOrder(orderId);
+```
+
+## Automation
+
+### Enable Auto-Withdraw
+
+```typescript
+await client.automation.enableAutoWithdraw({
+  campaignId: 1n,
+  frequency: 7 * 24 * 60 * 60, // Weekly
+  tipAmount: parseEther('0.1'), // Keeper tip
+});
+```
+
+### Enable Auto-Release for Locks
+
+```typescript
+await client.automation.enableAutoRelease({
+  campaignId: 5n,
+  tipAmount: parseEther('0.05'),
+});
+```
+
+### Check Automation Status
+
+```typescript
+const status = await client.automation.getAutoWithdrawStatus(campaignId);
+console.log('Enabled:', status.enabled);
+console.log('Next run:', new Date(status.nextRun * 1000));
+console.log('Tip balance:', status.tipBalance);
+```
+
+## API Client (Indexed Data)
+
+```typescript
+const client = new PepayStreamsClient({
+  rpcUrl: '...',
+  diamondAddress: '0x...',
+  chainId: 1,
+  apiBaseUrl: 'https://api.pepaystreams.com',
+});
+
+// Get campaigns with filtering
+const campaigns = await client.api.getCampaigns({
+  kind: 'vested_airdrop',
+  status: 'active',
+  page: 1,
+  pageSize: 20,
+});
+
+// Get wallet activity
+const activity = await client.api.getWalletActivity(address);
+
+// Get marketplace orders
+const orders = await client.api.getOrders({
+  orderType: 'tradable',
+  status: 'open',
+});
+```
+
+## React Integration
+
+See `@pepay-streams/sdk/react` for React-specific helpers:
+
+```typescript
+import { queryKeys, formatters } from '@pepay-streams/sdk/react';
+
+// Use with react-query
+const { data } = useQuery({
+  queryKey: queryKeys.campaign(campaignId),
+  queryFn: () => client.campaigns.getCampaign(campaignId),
+});
+
+// Format amounts
+formatters.formatTokenAmount(amount, 18); // "1,234.56"
+formatters.shortenAddress(address); // "0x1234...5678"
+```
+
+## Module Exports
+
+```typescript
+// Main client
+import { PepayStreamsClient } from '@pepay-streams/sdk';
+
+// Individual modules
+import { CampaignsModule } from '@pepay-streams/sdk/campaigns';
+import { ClaimsModule } from '@pepay-streams/sdk/claims';
+import { StakingModule } from '@pepay-streams/sdk/staking';
+import { MarketplaceModule } from '@pepay-streams/sdk/marketplace';
+import { AutomationModule } from '@pepay-streams/sdk/automation';
+import { ApiClient } from '@pepay-streams/sdk/api';
+
+// React helpers
+import { queryKeys, formatters } from '@pepay-streams/sdk/react';
+```
+
+## Types
+
+All types are fully exported:
+
+```typescript
+import type {
+  PepayStreamsConfig,
+  CampaignInfo,
+  PoolInfo,
+  OrderInfo,
+  RecipientStatus,
+  // ... and more
+} from '@pepay-streams/sdk';
+```
+
+## Supported Chains
+
+- Ethereum Mainnet (1)
+- BNB Smart Chain (56)
+- Local Anvil (31337)
+
+## License
+
+MIT

package/dist/api/index.d.mts

@@ -0,0 +1,321 @@
+import { Address } from 'viem';
+import { i as PaginatedResponse, j as ApiCampaign, k as ApiOrder, l as ApiStakingPool } from '../index-BTG0TRJt.mjs';
+
+/**
+ * API Client Module
+ *
+ * Provides methods for querying indexed blockchain data:
+ * - Campaign queries
+ * - Order queries
+ * - Wallet activity
+ * - Token information
+ * - Staking pool queries
+ */
+
+/**
+ * Query parameters for campaigns
+ */
+interface CampaignQueryParams {
+    /** Filter by campaign kind */
+    kind?: 'instant_airdrop' | 'vested_airdrop' | 'lock' | 'vesting';
+    /** Filter by creator address */
+    creator?: Address;
+    /** Filter by token address */
+    token?: Address;
+    /** Filter by status */
+    status?: 'active' | 'paused' | 'finalized';
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Items per page */
+    pageSize?: number;
+    /** Sort field */
+    sortBy?: 'createdAt' | 'totalAllocated' | 'recipientCount';
+    /** Sort direction */
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Query parameters for orders
+ */
+interface OrderQueryParams {
+    /** Filter by order type */
+    orderType?: 'instant' | 'vested' | 'tradable';
+    /** Filter by seller */
+    seller?: Address;
+    /** Filter by sell token */
+    sellToken?: Address;
+    /** Filter by pay token */
+    payToken?: Address;
+    /** Filter by status */
+    status?: 'open' | 'filled' | 'canceled' | 'expired';
+    /** Filter by campaign (for tradable) */
+    campaignId?: string;
+    /** Page number */
+    page?: number;
+    /** Items per page */
+    pageSize?: number;
+    /** Sort field */
+    sortBy?: 'createdAt' | 'totalPrice' | 'expiresAt';
+    /** Sort direction */
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Query parameters for staking pools
+ */
+interface PoolQueryParams {
+    /** Filter by stake token */
+    stakeToken?: Address;
+    /** Filter by reward token */
+    rewardToken?: Address;
+    /** Filter by creator */
+    creator?: Address;
+    /** Filter by active status */
+    isActive?: boolean;
+    /** Page number */
+    page?: number;
+    /** Items per page */
+    pageSize?: number;
+}
+/**
+ * Wallet activity summary
+ */
+interface WalletActivity {
+    address: Address;
+    /** Campaigns where wallet is a recipient */
+    campaigns: {
+        id: string;
+        kind: string;
+        allocated: string;
+        claimed: string;
+        due: string;
+    }[];
+    /** Open orders created by wallet */
+    openOrders: ApiOrder[];
+    /** Staking positions */
+    stakes: {
+        poolId: string;
+        amount: string;
+        pendingRewards: string;
+    }[];
+    /** Total value across all positions (in USD if available) */
+    totalValue?: string;
+}
+/**
+ * Token information from enrichment
+ */
+interface TokenInfo {
+    address: Address;
+    chainId: number;
+    symbol: string;
+    name: string;
+    decimals: number;
+    logoUrl?: string;
+    priceUsd?: string;
+    marketCap?: string;
+    volume24h?: string;
+}
+/**
+ * API client for indexed blockchain data
+ */
+declare class ApiClient {
+    private readonly baseUrl;
+    private readonly chainId;
+    constructor(baseUrl: string, chainId: number);
+    /**
+     * Get campaigns with optional filtering
+     *
+     * @example
+     * ```typescript
+     * const campaigns = await sdk.api.getCampaigns({
+     *   kind: 'vested_airdrop',
+     *   status: 'active',
+     *   page: 1,
+     *   pageSize: 20,
+     * });
+     * ```
+     */
+    getCampaigns(params?: CampaignQueryParams): Promise<PaginatedResponse<ApiCampaign>>;
+    /**
+     * Get a single campaign by ID
+     */
+    getCampaign(campaignId: string): Promise<ApiCampaign>;
+    /**
+     * Get campaign recipients
+     */
+    getCampaignRecipients(campaignId: string, params?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<PaginatedResponse<{
+        address: Address;
+        allocated: string;
+        claimed: string;
+        blocked: boolean;
+    }>>;
+    /**
+     * Get campaign activity/claims
+     */
+    getCampaignActivity(campaignId: string, params?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<PaginatedResponse<{
+        recipient: Address;
+        amount: string;
+        timestamp: string;
+        txHash: string;
+    }>>;
+    /**
+     * Get marketplace orders with optional filtering
+     *
+     * @example
+     * ```typescript
+     * const orders = await sdk.api.getOrders({
+     *   orderType: 'tradable',
+     *   status: 'open',
+     *   sortBy: 'totalPrice',
+     *   sortOrder: 'asc',
+     * });
+     * ```
+     */
+    getOrders(params?: OrderQueryParams): Promise<PaginatedResponse<ApiOrder>>;
+    /**
+     * Get a single order by ID
+     */
+    getOrder(orderId: string): Promise<ApiOrder>;
+    /**
+     * Get order price quote
+     */
+    getOrderQuote(orderId: string): Promise<{
+        totalPrice: string;
+        protocolFee: string;
+        sellerReceives: string;
+        isValid: boolean;
+    }>;
+    /**
+     * Get staking pools with optional filtering
+     */
+    getStakingPools(params?: PoolQueryParams): Promise<PaginatedResponse<ApiStakingPool>>;
+    /**
+     * Get a single staking pool by ID
+     */
+    getStakingPool(poolId: string): Promise<ApiStakingPool>;
+    /**
+     * Get stakers for a pool
+     */
+    getPoolStakers(poolId: string, params?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<PaginatedResponse<{
+        address: Address;
+        amount: string;
+        pendingRewards: string;
+    }>>;
+    /**
+     * Get wallet activity summary
+     *
+     * @example
+     * ```typescript
+     * const activity = await sdk.api.getWalletActivity(address);
+     * console.log('Campaigns:', activity.campaigns.length);
+     * console.log('Open orders:', activity.openOrders.length);
+     * console.log('Stakes:', activity.stakes.length);
+     * ```
+     */
+    getWalletActivity(address: Address): Promise<WalletActivity>;
+    /**
+     * Get wallet claims history
+     */
+    getWalletClaims(address: Address, params?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<PaginatedResponse<{
+        campaignId: string;
+        amount: string;
+        timestamp: string;
+        txHash: string;
+    }>>;
+    /**
+     * Get wallet positions (campaigns where wallet has allocations)
+     */
+    getWalletPositions(address: Address): Promise<{
+        campaignId: string;
+        kind: string;
+        token: Address;
+        allocated: string;
+        claimed: string;
+        due: string;
+        vestingProgress: number;
+    }[]>;
+    /**
+     * Search for tokens
+     *
+     * @example
+     * ```typescript
+     * const tokens = await sdk.api.searchTokens('USDC');
+     * ```
+     */
+    searchTokens(query: string): Promise<TokenInfo[]>;
+    /**
+     * Get token information by address
+     */
+    getToken(address: Address): Promise<TokenInfo>;
+    /**
+     * Get token price
+     */
+    getTokenPrice(address: Address): Promise<{
+        priceUsd: string;
+        priceChange24h: string;
+        timestamp: string;
+    }>;
+    /**
+     * Check API health
+     */
+    health(): Promise<{
+        status: 'ok' | 'degraded' | 'down';
+        indexerBlockHeight: number;
+        chainBlockHeight: number;
+        lag: number;
+    }>;
+    /**
+     * Get supported chains
+     */
+    getChains(): Promise<{
+        chainId: number;
+        name: string;
+        rpcUrl: string;
+        diamondAddress: Address;
+    }[]>;
+    /**
+     * Prepare a claim transaction
+     *
+     * Returns the calldata for a claim transaction.
+     */
+    prepareClaimTx(params: {
+        campaignId: string;
+        recipient: Address;
+    }): Promise<{
+        to: Address;
+        data: `0x${string}`;
+        value: string;
+        estimatedGas: string;
+    }>;
+    /**
+     * Prepare a fill order transaction
+     */
+    prepareFillOrderTx(params: {
+        orderId: string;
+    }): Promise<{
+        to: Address;
+        data: `0x${string}`;
+        value: string;
+        estimatedGas: string;
+    }>;
+    private fetch;
+}
+/**
+ * API error class
+ */
+declare class ApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
+export { ApiClient, ApiError, type CampaignQueryParams, type OrderQueryParams, type PoolQueryParams, type TokenInfo, type WalletActivity, ApiClient as default };