pepay-streams-sdk 0.1.0

package/src/types/index.ts

@@ -0,0 +1,631 @@
+/**
+ * Core types for Pepay Streams SDK
+ */
+import type { Address, Hash, Hex } from 'viem';
+
+// Re-export shared types
+export {
+  CampaignKind,
+  DeliveryKind,
+  OrderStatus,
+  ChangePolicy,
+  StartMode,
+  Visibility,
+  StatusBits,
+  type CampaignKindString,
+  type DeliveryKindString,
+  type OrderStatusString,
+  type ChangePolicyString,
+} from '@pepay-streams/shared';
+
+// ============================================================================
+// Core SDK Types
+// ============================================================================
+
+/**
+ * SDK configuration options
+ */
+export interface PepayStreamsConfig {
+  /** RPC URL for blockchain connection */
+  rpcUrl: string;
+  /** Diamond contract address */
+  diamondAddress: Address;
+  /** Chain ID (e.g., 1 for Ethereum, 56 for BSC, 31337 for local) */
+  chainId: number;
+  /** API base URL for indexed data (optional) */
+  apiBaseUrl?: string;
+  /** WETH address (auto-detected if not provided) */
+  wethAddress?: Address;
+  /** Permit2 address (canonical if not provided) */
+  permit2Address?: Address;
+}
+
+/**
+ * Transaction result from SDK operations
+ */
+export interface TransactionResult {
+  /** Transaction hash */
+  hash: Hash;
+  /** Wait for transaction confirmation */
+  wait: () => Promise<TransactionReceipt>;
+}
+
+/**
+ * Transaction receipt after confirmation
+ */
+export interface TransactionReceipt {
+  /** Block number */
+  blockNumber: bigint;
+  /** Transaction hash */
+  transactionHash: Hash;
+  /** Gas used */
+  gasUsed: bigint;
+  /** Status (1 = success, 0 = failed) */
+  status: 'success' | 'reverted';
+  /** Decoded logs/events */
+  logs: unknown[];
+}
+
+// ============================================================================
+// Recipient Types
+// ============================================================================
+
+/**
+ * Recipient allocation in a campaign
+ */
+export interface Recipient {
+  /** Recipient wallet address */
+  address: Address;
+  /** Allocated amount in wei */
+  amount: bigint;
+}
+
+/**
+ * Recipient with cliff override for vested campaigns
+ */
+export interface RecipientWithCliff extends Recipient {
+  /** Optional cliff duration override in seconds */
+  cliffDuration?: number;
+}
+
+/**
+ * Recipient status from contract
+ */
+export interface RecipientStatus {
+  /** Total allocated to recipient */
+  allocated: bigint;
+  /** Amount already claimed */
+  claimed: bigint;
+  /** Amount currently due (claimable now) */
+  due: bigint;
+  /** Whether recipient is blocked */
+  blocked: boolean;
+  /** Whether recipient has claimed all */
+  fullyVested: boolean;
+}
+
+// ============================================================================
+// Campaign Types
+// ============================================================================
+
+/**
+ * Base parameters for all campaign types
+ */
+export interface BaseCampaignParams {
+  /** Token to distribute */
+  token: Address;
+  /** Campaign name (max 32 bytes) - not stored on-chain */
+  name?: string;
+  /** Fee buffer for fee-on-transfer tokens in wei */
+  feeBuffer?: bigint;
+  /** Change policy for recipient updates */
+  changePolicy?: 'only_recipient' | 'only_creator' | 'both' | 'no_one';
+  /** Enable trading on marketplace */
+  attachDefaultRegistry?: boolean;
+  /** Whether campaign can be canceled */
+  cancelable?: boolean;
+  /** Whether recipients can only claim once */
+  claimOnce?: boolean;
+  /** Auto-claim incentive in basis points (for keepers) */
+  autoClaimIncentiveBps?: number;
+  /** Claim grace period in seconds */
+  claimGrace?: number;
+  /** Whether to unwrap WETH to native on claim */
+  unwrapWETH?: boolean;
+  /** WETH contract address (for unwrap feature) */
+  weth?: Address;
+}
+
+/**
+ * Parameters for creating an Instant Airdrop
+ */
+export interface InstantAirdropParams extends BaseCampaignParams {
+  /** List of recipients and amounts */
+  recipients: Recipient[];
+}
+
+/**
+ * Parameters for creating a Vested Airdrop
+ */
+export interface VestedAirdropParams extends BaseCampaignParams {
+  /** List of recipients and amounts */
+  recipients: RecipientWithCliff[];
+  /** Vesting start timestamp (Unix seconds) */
+  startTime: number;
+  /** Total vesting duration in seconds */
+  duration: number;
+  /** Cliff duration in seconds (tokens locked until cliff passes) */
+  cliffDuration?: number;
+  /** Number of vesting steps (releases are linear between steps) */
+  steps?: number;
+  /** Cliff release percentage in basis points (0-10000) */
+  cliffBps?: number;
+}
+
+/**
+ * Parameters for creating a Token Lock
+ */
+export interface LockParams extends BaseCampaignParams {
+  /** Recipient of the locked tokens */
+  recipient: Address;
+  /** Amount to lock in wei */
+  amount: bigint;
+  /** Unlock timestamp (Unix seconds) */
+  unlockTime: number;
+}
+
+/**
+ * Parameters for creating a Vesting stream (Payment)
+ */
+export interface VestingParams extends BaseCampaignParams {
+  /** Recipient of the vesting stream */
+  recipient: Address;
+  /** Total amount to vest in wei */
+  amount: bigint;
+  /** Vesting start timestamp (Unix seconds) */
+  startTime: number;
+  /** Total vesting duration in seconds */
+  duration: number;
+  /** Cliff duration in seconds */
+  cliffDuration?: number;
+  /** Number of vesting steps */
+  steps?: number;
+  /** Cliff release percentage in basis points (0-10000) */
+  cliffBps?: number;
+  /** Enable auto-withdraw automation */
+  enableAutoWithdraw?: boolean;
+  /** Auto-withdraw frequency in seconds */
+  autoWithdrawFrequency?: number;
+}
+
+/**
+ * Campaign info from contract
+ */
+export interface CampaignInfo {
+  /** Campaign ID */
+  id: bigint;
+  /** Campaign kind/type */
+  kind: 'instant_airdrop' | 'vested_airdrop' | 'lock' | 'vesting';
+  /** Token being distributed */
+  token: Address;
+  /** Campaign creator */
+  creator: Address;
+  /** Campaign name (not stored on-chain, may be empty) */
+  name: string;
+  /** Total allocated amount */
+  totalAllocated: bigint;
+  /** Total funded amount */
+  totalFunded: bigint;
+  /** Total claimed amount */
+  totalClaimed: bigint;
+  /** Total returned to creator */
+  totalReturned: bigint;
+  /** Fee loss from transfers */
+  feeLoss: bigint;
+  /** Fee buffer remaining */
+  feeBuffer: bigint;
+  /** Vesting start time */
+  startTime: number;
+  /** Vesting end time */
+  endTime: number;
+  /** Cliff end time */
+  cliffTime: number;
+  /** Number of vesting steps */
+  steps: number;
+  /** Number of recipients */
+  recipientCount: number;
+  /** Status bits (paused, finalized, etc.) */
+  statusBits: number;
+  /** Change policy */
+  changePolicy: number;
+  /** Whether automation is enabled */
+  hasAutomation: boolean;
+  /** Whether campaign has a trading registry attached */
+  hasRegistry?: boolean;
+  /** Merkle root for merkle-based campaigns */
+  merkleRoot?: Hex;
+}
+
+// ============================================================================
+// Staking Types
+// ============================================================================
+
+/**
+ * Parameters for creating a staking pool
+ */
+export interface CreatePoolParams {
+  /** Token users stake */
+  stakeToken: Address;
+  /** Token users earn as rewards */
+  rewardToken: Address;
+  /** Total reward budget in wei */
+  rewardBudget: bigint;
+  /** Pool duration in seconds */
+  duration: number;
+  /** Minimum stake amount (optional) */
+  minStake?: bigint;
+  /** Maximum stake per user (optional, 0 = unlimited) */
+  maxStake?: bigint;
+  /** Pool name for identification */
+  name?: string;
+}
+
+/**
+ * Staking pool info from contract
+ */
+export interface PoolInfo {
+  /** Pool ID */
+  id: bigint;
+  /** Token being staked */
+  stakeToken: Address;
+  /** Reward token */
+  rewardToken: Address;
+  /** Pool creator */
+  creator: Address;
+  /** Total staked amount */
+  totalStaked: bigint;
+  /** Total reward budget */
+  rewardBudget: bigint;
+  /** Rewards distributed so far */
+  rewardsDistributed: bigint;
+  /** Pool start time */
+  startTime: number;
+  /** Pool end time */
+  endTime: number;
+  /** Minimum stake amount */
+  minStake: bigint;
+  /** Maximum stake per user */
+  maxStake: bigint;
+  /** Number of stakers */
+  stakerCount: number;
+  /** Whether pool is active */
+  isActive: boolean;
+  /** Whether pool is finalized */
+  isFinalized: boolean;
+}
+
+/**
+ * User stake info
+ */
+export interface UserStake {
+  /** Amount staked */
+  amount: bigint;
+  /** Pending rewards */
+  pendingRewards: bigint;
+  /** Last claim timestamp */
+  lastClaimTime: number;
+  /** Stake start time */
+  stakeTime: number;
+}
+
+// ============================================================================
+// Marketplace Types
+// ============================================================================
+
+/**
+ * Order type for marketplace
+ */
+export type OrderType = 'instant' | 'vested' | 'tradable';
+
+/**
+ * Parameters for creating an INSTANT order
+ */
+export interface CreateInstantOrderParams {
+  /** Token to sell */
+  sellToken: Address;
+  /** Amount to sell in wei */
+  sellAmount: bigint;
+  /** Token to receive as payment */
+  payToken: Address;
+  /** Price per token in pay token wei */
+  pricePerToken: bigint;
+  /** Private buyers (empty = public) */
+  privateBuyers?: Address[];
+  /** Order expiry TTL in seconds */
+  expiryTTL?: number;
+}
+
+/**
+ * Parameters for creating a VESTED order
+ */
+export interface CreateVestedOrderParams extends CreateInstantOrderParams {
+  /** Vesting duration in seconds */
+  vestingDuration: number;
+  /** Cliff duration in seconds */
+  cliffDuration?: number;
+  /** Start mode: when vesting starts */
+  startMode?: 'upon_fill' | 'fixed_timestamp';
+  /** Fixed start timestamp (if startMode is fixed_timestamp) */
+  fixedStartTime?: number;
+}
+
+/**
+ * Parameters for creating a TRADABLE order (listing unvested position)
+ */
+export interface CreateTradableOrderParams {
+  /** Campaign ID to list position from */
+  campaignId: bigint;
+  /** Price per token in pay token wei */
+  pricePerToken: bigint;
+  /** Token to receive as payment (use zero address for native) */
+  payToken: Address;
+  /** Private buyers (empty = public) */
+  privateBuyers?: Address[];
+  /** Order expiry TTL in seconds */
+  expiryTTL?: number;
+}
+
+/**
+ * Marketplace order info
+ */
+export interface OrderInfo {
+  /** Order ID */
+  id: bigint;
+  /** Order type */
+  orderType: OrderType;
+  /** Seller address */
+  seller: Address;
+  /** Token being sold */
+  sellToken: Address;
+  /** Amount being sold */
+  sellAmount: bigint;
+  /** Payment token */
+  payToken: Address;
+  /** Total price */
+  totalPrice: bigint;
+  /** Price per token */
+  pricePerToken: bigint;
+  /** Order status */
+  status: 'open' | 'filled' | 'canceled' | 'expired';
+  /** Buyer (if filled) */
+  buyer?: Address;
+  /** Creation timestamp */
+  createdAt: number;
+  /** Expiry timestamp */
+  expiresAt: number;
+  /** Associated campaign ID (for tradable) */
+  campaignId?: bigint;
+  /** Vesting params (for vested orders) */
+  vestingDuration?: number;
+  cliffDuration?: number;
+}
+
+/**
+ * Quote for filling an order
+ */
+export interface OrderQuote {
+  /** Order ID */
+  orderId: bigint;
+  /** Total price to pay */
+  totalPrice: bigint;
+  /** Protocol fee */
+  protocolFee: bigint;
+  /** Amount buyer receives */
+  buyerReceives: bigint;
+  /** Amount seller receives after fees */
+  sellerReceives: bigint;
+  /** Whether order is still valid */
+  isValid: boolean;
+  /** Expiry timestamp */
+  expiresAt: number;
+}
+
+// ============================================================================
+// Automation Types
+// ============================================================================
+
+/**
+ * Parameters for enabling auto-withdraw
+ */
+export interface EnableAutoWithdrawParams {
+  /** Campaign ID */
+  campaignId: bigint;
+  /** Frequency in seconds between auto-withdraws */
+  frequency: number;
+  /** Tip amount in native wei for keeper */
+  tipAmount?: bigint;
+}
+
+/**
+ * Parameters for enabling auto-release (locks)
+ */
+export interface EnableAutoReleaseParams {
+  /** Campaign ID (must be a Lock) */
+  campaignId: bigint;
+  /** Tip amount in native wei for keeper */
+  tipAmount?: bigint;
+}
+
+/**
+ * Automation status for a campaign
+ */
+export interface AutomationStatus {
+  /** Whether automation is enabled */
+  enabled: boolean;
+  /** Last run timestamp */
+  lastRun: number;
+  /** Next eligible run timestamp */
+  nextRun: number;
+  /** Frequency between runs */
+  frequency: number;
+  /** Remaining tip balance */
+  tipBalance: bigint;
+  /** Number of recipients processed */
+  recipientsProcessed: number;
+  /** Total recipients */
+  totalRecipients: number;
+}
+
+// ============================================================================
+// Claim Types
+// ============================================================================
+
+/**
+ * Claim parameters
+ *
+ * For direct campaigns, allocation should be 0n and proof should be empty [].
+ * For merkle campaigns, provide allocation and proof.
+ */
+export interface ClaimParams {
+  /** Campaign ID */
+  campaignId: bigint;
+  /** Allocation amount for merkle claims (0 for direct campaigns) */
+  allocation?: bigint;
+  /** Merkle proof (empty array for direct campaigns) */
+  proof?: Hex[];
+  /** Claim to specific address (optional, defaults to caller) */
+  claimTo?: Address;
+}
+
+/**
+ * Batch claim parameters - claims for multiple recipients in a single campaign
+ */
+export interface BatchClaimParams {
+  /** Campaign ID */
+  campaignId: bigint;
+  /** List of recipients to claim for */
+  recipients: Address[];
+}
+
+/**
+ * Meta-transaction claim parameters (gasless)
+ *
+ * All fields from the ClaimAuth struct required for signature verification.
+ */
+export interface MetaClaimParams {
+  /** Campaign ID */
+  campaignId: bigint;
+  /** Claimant address (who is claiming) */
+  claimant: Address;
+  /** Payout destination (optional, defaults to claimant) */
+  payoutTo?: Address;
+  /** Allocation amount */
+  allocation: bigint;
+  /** Merkle proof (empty array for direct campaigns) */
+  proof: Hex[];
+  /** EIP-712 signature from claimant */
+  signature: Hex;
+  /** Signature deadline timestamp (Unix seconds) */
+  deadline: number;
+  /** Nonce for replay protection */
+  nonce: bigint;
+}
+
+/**
+ * Merkle claim parameters
+ */
+export interface MerkleClaimParams {
+  /** Campaign ID */
+  campaignId: bigint;
+  /** Claimable amount */
+  amount: bigint;
+  /** Merkle proof */
+  proof: Hex[];
+}
+
+/**
+ * Claim result
+ */
+export interface ClaimResult {
+  /** Transaction hash */
+  hash: Hash;
+  /** Amount claimed (gross) */
+  grossAmount: bigint;
+  /** Amount received (net, after any token fees) */
+  netAmount: bigint;
+  /** Whether fee was waived due to token issues */
+  feeWaived: boolean;
+}
+
+// ============================================================================
+// API Response Types
+// ============================================================================
+
+/**
+ * Paginated response wrapper
+ */
+export interface PaginatedResponse<T> {
+  /** Data items */
+  data: T[];
+  /** Total count */
+  total: number;
+  /** Current page */
+  page: number;
+  /** Items per page */
+  pageSize: number;
+  /** Whether more pages exist */
+  hasMore: boolean;
+}
+
+/**
+ * API campaign response (from indexed data)
+ */
+export interface ApiCampaign {
+  id: string;
+  chainId: number;
+  kind: string;
+  token: Address;
+  creator: Address;
+  name: string;
+  totalAllocated: string;
+  totalClaimed: string;
+  recipientCount: number;
+  startTime: string;
+  endTime: string;
+  createdAt: string;
+  status: string;
+}
+
+/**
+ * API order response (from indexed data)
+ */
+export interface ApiOrder {
+  id: string;
+  chainId: number;
+  orderType: string;
+  seller: Address;
+  sellToken: Address;
+  sellAmount: string;
+  payToken: Address;
+  totalPrice: string;
+  status: string;
+  createdAt: string;
+  expiresAt: string;
+}
+
+/**
+ * API staking pool response (from indexed data)
+ */
+export interface ApiStakingPool {
+  id: string;
+  chainId: number;
+  stakeToken: Address;
+  rewardToken: Address;
+  creator: Address;
+  totalStaked: string;
+  rewardBudget: string;
+  startTime: string;
+  endTime: string;
+  isActive: boolean;
+  stakerCount: number;
+}