pepay-streams-sdk 0.1.0

package/src/api/index.ts

@@ -0,0 +1,577 @@
+/**
+ * API Client Module
+ *
+ * Provides methods for querying indexed blockchain data:
+ * - Campaign queries
+ * - Order queries
+ * - Wallet activity
+ * - Token information
+ * - Staking pool queries
+ */
+import type { Address } from 'viem';
+import type {
+  ApiCampaign,
+  ApiOrder,
+  ApiStakingPool,
+  PaginatedResponse,
+} from '../types';
+
+/**
+ * Query parameters for campaigns
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export class ApiClient {
+  private readonly baseUrl: string;
+  private readonly chainId: number;
+
+  constructor(baseUrl: string, chainId: number) {
+    this.baseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+    this.chainId = chainId;
+  }
+
+  // ============================================================================
+  // Campaign Queries
+  // ============================================================================
+
+  /**
+   * Get campaigns with optional filtering
+   *
+   * @example
+   * ```typescript
+   * const campaigns = await sdk.api.getCampaigns({
+   *   kind: 'vested_airdrop',
+   *   status: 'active',
+   *   page: 1,
+   *   pageSize: 20,
+   * });
+   * ```
+   */
+  async getCampaigns(
+    params: CampaignQueryParams = {}
+  ): Promise<PaginatedResponse<ApiCampaign>> {
+    const searchParams = new URLSearchParams();
+
+    if (params.kind) searchParams.set('kind', params.kind);
+    if (params.creator) searchParams.set('creator', params.creator);
+    if (params.token) searchParams.set('token', params.token);
+    if (params.status) searchParams.set('status', params.status);
+    if (params.page) searchParams.set('page', String(params.page));
+    if (params.pageSize) searchParams.set('pageSize', String(params.pageSize));
+    if (params.sortBy) searchParams.set('sortBy', params.sortBy);
+    if (params.sortOrder) searchParams.set('sortOrder', params.sortOrder);
+
+    searchParams.set('chainId', String(this.chainId));
+
+    return this.fetch<PaginatedResponse<ApiCampaign>>(
+      `/v1/campaigns?${searchParams.toString()}`
+    );
+  }
+
+  /**
+   * Get a single campaign by ID
+   */
+  async getCampaign(campaignId: string): Promise<ApiCampaign> {
+    return this.fetch<ApiCampaign>(
+      `/v1/campaigns/${campaignId}?chainId=${this.chainId}`
+    );
+  }
+
+  /**
+   * Get campaign recipients
+   */
+  async getCampaignRecipients(
+    campaignId: string,
+    params: { page?: number; pageSize?: number } = {}
+  ): Promise<
+    PaginatedResponse<{
+      address: Address;
+      allocated: string;
+      claimed: string;
+      blocked: boolean;
+    }>
+  > {
+    const searchParams = new URLSearchParams();
+    searchParams.set('chainId', String(this.chainId));
+    if (params.page) searchParams.set('page', String(params.page));
+    if (params.pageSize) searchParams.set('pageSize', String(params.pageSize));
+
+    return this.fetch(
+      `/v1/campaigns/${campaignId}/recipients?${searchParams.toString()}`
+    );
+  }
+
+  /**
+   * Get campaign activity/claims
+   */
+  async getCampaignActivity(
+    campaignId: string,
+    params: { page?: number; pageSize?: number } = {}
+  ): Promise<
+    PaginatedResponse<{
+      recipient: Address;
+      amount: string;
+      timestamp: string;
+      txHash: string;
+    }>
+  > {
+    const searchParams = new URLSearchParams();
+    searchParams.set('chainId', String(this.chainId));
+    if (params.page) searchParams.set('page', String(params.page));
+    if (params.pageSize) searchParams.set('pageSize', String(params.pageSize));
+
+    return this.fetch(
+      `/v1/campaigns/${campaignId}/activity?${searchParams.toString()}`
+    );
+  }
+
+  // ============================================================================
+  // Order Queries
+  // ============================================================================
+
+  /**
+   * Get marketplace orders with optional filtering
+   *
+   * @example
+   * ```typescript
+   * const orders = await sdk.api.getOrders({
+   *   orderType: 'tradable',
+   *   status: 'open',
+   *   sortBy: 'totalPrice',
+   *   sortOrder: 'asc',
+   * });
+   * ```
+   */
+  async getOrders(
+    params: OrderQueryParams = {}
+  ): Promise<PaginatedResponse<ApiOrder>> {
+    const searchParams = new URLSearchParams();
+
+    if (params.orderType) searchParams.set('orderType', params.orderType);
+    if (params.seller) searchParams.set('seller', params.seller);
+    if (params.sellToken) searchParams.set('sellToken', params.sellToken);
+    if (params.payToken) searchParams.set('payToken', params.payToken);
+    if (params.status) searchParams.set('status', params.status);
+    if (params.campaignId) searchParams.set('campaignId', params.campaignId);
+    if (params.page) searchParams.set('page', String(params.page));
+    if (params.pageSize) searchParams.set('pageSize', String(params.pageSize));
+    if (params.sortBy) searchParams.set('sortBy', params.sortBy);
+    if (params.sortOrder) searchParams.set('sortOrder', params.sortOrder);
+
+    searchParams.set('chainId', String(this.chainId));
+
+    return this.fetch<PaginatedResponse<ApiOrder>>(
+      `/v1/marketplace/orders?${searchParams.toString()}`
+    );
+  }
+
+  /**
+   * Get a single order by ID
+   */
+  async getOrder(orderId: string): Promise<ApiOrder> {
+    return this.fetch<ApiOrder>(
+      `/v1/marketplace/orders/${orderId}?chainId=${this.chainId}`
+    );
+  }
+
+  /**
+   * Get order price quote
+   */
+  async getOrderQuote(orderId: string): Promise<{
+    totalPrice: string;
+    protocolFee: string;
+    sellerReceives: string;
+    isValid: boolean;
+  }> {
+    return this.fetch(
+      `/v1/marketplace/orders/${orderId}/quote?chainId=${this.chainId}`
+    );
+  }
+
+  // ============================================================================
+  // Staking Queries
+  // ============================================================================
+
+  /**
+   * Get staking pools with optional filtering
+   */
+  async getStakingPools(
+    params: PoolQueryParams = {}
+  ): Promise<PaginatedResponse<ApiStakingPool>> {
+    const searchParams = new URLSearchParams();
+
+    if (params.stakeToken) searchParams.set('stakeToken', params.stakeToken);
+    if (params.rewardToken) searchParams.set('rewardToken', params.rewardToken);
+    if (params.creator) searchParams.set('creator', params.creator);
+    if (params.isActive !== undefined)
+      searchParams.set('isActive', String(params.isActive));
+    if (params.page) searchParams.set('page', String(params.page));
+    if (params.pageSize) searchParams.set('pageSize', String(params.pageSize));
+
+    searchParams.set('chainId', String(this.chainId));
+
+    return this.fetch<PaginatedResponse<ApiStakingPool>>(
+      `/v1/staking/pools?${searchParams.toString()}`
+    );
+  }
+
+  /**
+   * Get a single staking pool by ID
+   */
+  async getStakingPool(poolId: string): Promise<ApiStakingPool> {
+    return this.fetch<ApiStakingPool>(
+      `/v1/staking/pools/${poolId}?chainId=${this.chainId}`
+    );
+  }
+
+  /**
+   * Get stakers for a pool
+   */
+  async getPoolStakers(
+    poolId: string,
+    params: { page?: number; pageSize?: number } = {}
+  ): Promise<
+    PaginatedResponse<{
+      address: Address;
+      amount: string;
+      pendingRewards: string;
+    }>
+  > {
+    const searchParams = new URLSearchParams();
+    searchParams.set('chainId', String(this.chainId));
+    if (params.page) searchParams.set('page', String(params.page));
+    if (params.pageSize) searchParams.set('pageSize', String(params.pageSize));
+
+    return this.fetch(
+      `/v1/staking/pools/${poolId}/stakers?${searchParams.toString()}`
+    );
+  }
+
+  // ============================================================================
+  // Wallet Queries
+  // ============================================================================
+
+  /**
+   * 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);
+   * ```
+   */
+  async getWalletActivity(address: Address): Promise<WalletActivity> {
+    return this.fetch<WalletActivity>(
+      `/v1/wallets/${address}?chainId=${this.chainId}`
+    );
+  }
+
+  /**
+   * Get wallet claims history
+   */
+  async getWalletClaims(
+    address: Address,
+    params: { page?: number; pageSize?: number } = {}
+  ): Promise<
+    PaginatedResponse<{
+      campaignId: string;
+      amount: string;
+      timestamp: string;
+      txHash: string;
+    }>
+  > {
+    const searchParams = new URLSearchParams();
+    searchParams.set('chainId', String(this.chainId));
+    if (params.page) searchParams.set('page', String(params.page));
+    if (params.pageSize) searchParams.set('pageSize', String(params.pageSize));
+
+    return this.fetch(
+      `/v1/wallets/${address}/claims?${searchParams.toString()}`
+    );
+  }
+
+  /**
+   * Get wallet positions (campaigns where wallet has allocations)
+   */
+  async getWalletPositions(
+    address: Address
+  ): Promise<
+    {
+      campaignId: string;
+      kind: string;
+      token: Address;
+      allocated: string;
+      claimed: string;
+      due: string;
+      vestingProgress: number;
+    }[]
+  > {
+    return this.fetch(
+      `/v1/wallets/${address}/positions?chainId=${this.chainId}`
+    );
+  }
+
+  // ============================================================================
+  // Token Queries
+  // ============================================================================
+
+  /**
+   * Search for tokens
+   *
+   * @example
+   * ```typescript
+   * const tokens = await sdk.api.searchTokens('USDC');
+   * ```
+   */
+  async searchTokens(query: string): Promise<TokenInfo[]> {
+    return this.fetch<TokenInfo[]>(
+      `/v1/tokens?q=${encodeURIComponent(query)}&chainId=${this.chainId}`
+    );
+  }
+
+  /**
+   * Get token information by address
+   */
+  async getToken(address: Address): Promise<TokenInfo> {
+    return this.fetch<TokenInfo>(
+      `/v1/tokens/${address}?chainId=${this.chainId}`
+    );
+  }
+
+  /**
+   * Get token price
+   */
+  async getTokenPrice(address: Address): Promise<{
+    priceUsd: string;
+    priceChange24h: string;
+    timestamp: string;
+  }> {
+    return this.fetch(
+      `/v1/tokens/${address}/price?chainId=${this.chainId}`
+    );
+  }
+
+  // ============================================================================
+  // Health & Status
+  // ============================================================================
+
+  /**
+   * Check API health
+   */
+  async health(): Promise<{
+    status: 'ok' | 'degraded' | 'down';
+    indexerBlockHeight: number;
+    chainBlockHeight: number;
+    lag: number;
+  }> {
+    return this.fetch('/health');
+  }
+
+  /**
+   * Get supported chains
+   */
+  async getChains(): Promise<
+    {
+      chainId: number;
+      name: string;
+      rpcUrl: string;
+      diamondAddress: Address;
+    }[]
+  > {
+    return this.fetch('/v1/chains');
+  }
+
+  // ============================================================================
+  // Actions (Transaction Preparation)
+  // ============================================================================
+
+  /**
+   * Prepare a claim transaction
+   *
+   * Returns the calldata for a claim transaction.
+   */
+  async prepareClaimTx(params: {
+    campaignId: string;
+    recipient: Address;
+  }): Promise<{
+    to: Address;
+    data: `0x${string}`;
+    value: string;
+    estimatedGas: string;
+  }> {
+    return this.fetch('/v1/actions/claim', {
+      method: 'POST',
+      body: JSON.stringify({
+        ...params,
+        chainId: this.chainId,
+      }),
+    });
+  }
+
+  /**
+   * Prepare a fill order transaction
+   */
+  async prepareFillOrderTx(params: {
+    orderId: string;
+  }): Promise<{
+    to: Address;
+    data: `0x${string}`;
+    value: string;
+    estimatedGas: string;
+  }> {
+    return this.fetch('/v1/actions/fill-order', {
+      method: 'POST',
+      body: JSON.stringify({
+        ...params,
+        chainId: this.chainId,
+      }),
+    });
+  }
+
+  // ============================================================================
+  // Helpers
+  // ============================================================================
+
+  private async fetch<T>(
+    endpoint: string,
+    options: RequestInit = {}
+  ): Promise<T> {
+    const url = `${this.baseUrl}${endpoint}`;
+
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        'Content-Type': 'application/json',
+        ...options.headers,
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new ApiError(response.status, error);
+    }
+
+    return response.json() as Promise<T>;
+  }
+}
+
+/**
+ * API error class
+ */
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string
+  ) {
+    super(`API Error (${status}): ${message}`);
+    this.name = 'ApiError';
+  }
+}
+
+export default ApiClient;