@pompafly/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,382 @@
+import * as _solana_web3_js from '@solana/web3.js';
+import { PublicKey, Keypair, Connection } from '@solana/web3.js';
+
+interface PompaflyConfig {
+    /** Solana RPC endpoint URL */
+    rpcUrl: string;
+    /** Pompafly program ID */
+    programId: string;
+    /** Backend API base URL */
+    apiUrl: string;
+    /** WebSocket URL for real-time feeds */
+    wsUrl: string;
+}
+declare const DEVNET_CONFIG: PompaflyConfig;
+declare const MAINNET_CONFIG: PompaflyConfig;
+/** Compatible with @solana/wallet-adapter AnchorWallet interface */
+interface WalletAdapter {
+    publicKey: PublicKey;
+    signTransaction: <T extends _solana_web3_js.Transaction | _solana_web3_js.VersionedTransaction>(tx: T) => Promise<T>;
+    signAllTransactions: <T extends _solana_web3_js.Transaction | _solana_web3_js.VersionedTransaction>(txs: T[]) => Promise<T[]>;
+}
+interface Pool {
+    mint: string;
+    poolAddress: string;
+    creator: string;
+    creatorXHandle: string;
+    name: string;
+    symbol: string;
+    uri: string;
+    status: "active" | "graduating" | "graduated";
+    totalSupply: string;
+    supplySold: string;
+    solBalance: string;
+    currentPrice: string;
+    marketCap: string;
+    progressPercent: number;
+    priorityWindowEnd: string;
+    graduatedAt: string | null;
+    totalTrades: number;
+    totalVolumeSol: string;
+    holderCount: number;
+    createdAt: string;
+}
+interface PoolPrice {
+    currentPrice: string;
+    marketCap: string;
+    solBalance: string;
+    supplySold: string;
+    progressPercent: number;
+    graduationThreshold: string;
+    isPriorityWindow: boolean;
+    status: string;
+}
+interface PoolListParams {
+    page?: number;
+    limit?: number;
+    status?: "active" | "graduating" | "graduated";
+    sort?: "newest" | "oldest" | "volume" | "marketcap" | "graduating";
+    search?: string;
+    creator?: string;
+}
+interface Trade {
+    pool: string;
+    mint: string;
+    trader: string;
+    type: "buy" | "sell";
+    tokenAmount: string;
+    solAmount: string;
+    fee: string;
+    price: string;
+    txSignature: string;
+    timestamp: string;
+}
+interface TradeListParams {
+    page?: number;
+    limit?: number;
+    type?: "buy" | "sell";
+    trader?: string;
+}
+interface Candle {
+    timestamp: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+    tradeCount: number;
+}
+type CandleInterval = "1m" | "5m" | "15m" | "1h" | "4h" | "1d";
+interface CandleParams {
+    interval: CandleInterval;
+    from?: number;
+    to?: number;
+    limit?: number;
+}
+interface User {
+    wallet: string;
+    xHandle: string;
+    xVerified: boolean;
+    isCreator: boolean;
+    totalTrades: number;
+    totalVolumeSol: string;
+    createdAt: string;
+}
+interface PlatformStats {
+    totalPoolsCreated: number;
+    totalPoolsGraduated: number;
+    graduationRate: string;
+    activePoolsCount: number;
+    totalUsers: number;
+    totalTrades: number;
+    totalVolumeSol: string;
+    totalFeesCollected: string;
+}
+interface TrendingPool {
+    mint: string;
+    name: string;
+    symbol: string;
+    creatorXHandle: string;
+    status: string;
+    volume24h: string;
+    trades24h: number;
+    currentPrice: string;
+    marketCap: string;
+    progressPercent: number;
+}
+interface TxResult {
+    signature: string;
+    slot?: number;
+}
+interface BuyResult extends TxResult {
+    tokenAmount: string;
+    solCost: string;
+}
+interface SellResult extends TxResult {
+    tokenAmount: string;
+    solReceived: string;
+}
+interface CreatePoolResult extends TxResult {
+    mint: string;
+    pool: string;
+}
+interface ApiResponse<T> {
+    success: boolean;
+    data: T;
+    error?: string;
+    code?: string;
+}
+interface PaginatedResponse<T> extends ApiResponse<T[]> {
+    pagination: {
+        total: number;
+        page: number;
+        limit: number;
+        pages: number;
+    };
+}
+interface PriceEvent {
+    type: "price";
+    mint: string;
+    data: PoolPrice;
+}
+interface TradeEvent {
+    type: "trade";
+    mint: string;
+    data: Trade;
+}
+interface StatusEvent {
+    type: "status";
+    mint: string;
+    data: {
+        oldStatus: string;
+        newStatus: string;
+    };
+}
+type StreamEvent = PriceEvent | TradeEvent | StatusEvent;
+type StreamEventHandler = (event: StreamEvent) => void;
+
+/**
+ * ─────────────────────────────────────────────────────────────
+ * PompaflyClient — on-chain transaction builder
+ *
+ * Builds and sends Solana transactions for the Pompafly program.
+ * No dependency on anchor.Program — uses raw instruction encoding.
+ *
+ * Usage with wallet adapter (frontend):
+ *   const client = new PompaflyClient({ wallet });
+ *
+ * Usage with keypair (backend/scripts):
+ *   const client = new PompaflyClient({ keypair });
+ * ─────────────────────────────────────────────────────────────
+ */
+interface ClientOptions {
+    wallet?: WalletAdapter;
+    keypair?: Keypair;
+    config?: PompaflyConfig;
+    connection?: Connection;
+}
+declare class PompaflyClient {
+    readonly connection: Connection;
+    readonly programId: PublicKey;
+    readonly config: PompaflyConfig;
+    private wallet;
+    private globalConfigPda;
+    constructor(options: ClientOptions);
+    get publicKey(): PublicKey;
+    private sendTx;
+    createPool(name: string, symbol: string, uri: string, creatorXHandle: string, authoritySigner: Keypair): Promise<CreatePoolResult>;
+    buy(mint: string | PublicKey, tokenAmount: number, maxSlippageSol: number, prioritySigner?: Keypair): Promise<BuyResult>;
+    sell(mint: string | PublicKey, tokenAmount: number, minReturnSol?: number): Promise<SellResult>;
+    collectFees(mint: string | PublicKey, validatorWallet: string | PublicKey, communityWallet: string | PublicKey, platformWallet: string | PublicKey): Promise<TxResult>;
+    graduate(mint: string | PublicKey): Promise<TxResult>;
+    /**
+     * Get raw account data for a pool PDA.
+     * Returns the raw bytes — use with the Anchor IDL for full deserialization,
+     * or parse manually if you know the layout.
+     */
+    getPoolAccountInfo(mint: string | PublicKey): Promise<_solana_web3_js.AccountInfo<Buffer<ArrayBufferLike>> | null>;
+    /** Get the pool PDA address for a given mint */
+    getPoolAddress(mint: string | PublicKey): Promise<string>;
+    /** Get the token vault ATA address for a pool */
+    getPoolTokenVault(mint: string | PublicKey): Promise<string>;
+    /** Get the global config PDA address */
+    getGlobalConfigAddress(): string;
+}
+
+/**
+ * ─────────────────────────────────────────────────────────────
+ * PompaflyAPI — REST API client
+ *
+ * Wraps all backend endpoints with typed responses.
+ * Handles JWT auth automatically after login.
+ *
+ * Usage:
+ *   const api = new PompaflyAPI();
+ *   const pools = await api.getPools({ sort: "trending" });
+ *   await api.login(wallet, signature);
+ *   const me = await api.getMe();
+ * ─────────────────────────────────────────────────────────────
+ */
+declare class PompaflyAPI {
+    private baseUrl;
+    private token;
+    constructor(config?: PompaflyConfig);
+    /** Set JWT token for authenticated requests */
+    setToken(token: string): void;
+    /** Clear authentication */
+    clearToken(): void;
+    private fetch;
+    /** Request a login nonce for wallet signature */
+    getNonce(wallet: string): Promise<ApiResponse<{
+        nonce: string;
+        message: string;
+    }>>;
+    /** Verify wallet signature and get JWT */
+    verifyWallet(wallet: string, signature: string): Promise<ApiResponse<{
+        token: string;
+        user: User;
+    }>>;
+    /** Get X OAuth login URL (must be authenticated first) */
+    getXLoginUrl(): string;
+    /** Get current user profile */
+    getMe(): Promise<ApiResponse<User>>;
+    /** List pools with filters and sorting */
+    getPools(params?: PoolListParams): Promise<PaginatedResponse<Pool>>;
+    /** Get pool details by mint */
+    getPool(mint: string): Promise<ApiResponse<Pool>>;
+    /** Get current price and curve position */
+    getPoolPrice(mint: string): Promise<ApiResponse<PoolPrice>>;
+    /** Get top holders for a pool */
+    getHolders(mint: string, limit?: number): Promise<ApiResponse<{
+        holders: any[];
+        totalHolders: number;
+    }>>;
+    /** Get trade history for a pool */
+    getTrades(mint: string, params?: TradeListParams): Promise<PaginatedResponse<Trade>>;
+    /** Get OHLCV candle data for charts */
+    getCandles(mint: string, params: CandleParams): Promise<ApiResponse<Candle[]>>;
+    /** Get trade history for a specific wallet */
+    getUserTrades(wallet: string, params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<Trade>>;
+    /** Get a priority buy authorization (requires X verification) */
+    getPriorityAuth(mint: string): Promise<ApiResponse<{
+        signature: string;
+        pool: string;
+        wallet: string;
+        expiresAt: number;
+    }>>;
+    /** Check priority window status */
+    getPriorityStatus(mint: string): Promise<ApiResponse<{
+        isActive: boolean;
+        endsAt: string;
+        remainingSeconds: number;
+    }>>;
+    /** Get platform-wide statistics */
+    getStats(): Promise<ApiResponse<PlatformStats>>;
+    /** Get trending pools (24h volume) */
+    getTrending(limit?: number): Promise<ApiResponse<TrendingPool[]>>;
+    /** Get trader leaderboard */
+    getLeaderboard(params?: {
+        limit?: number;
+        period?: string;
+    }): Promise<ApiResponse<any[]>>;
+    /** Get fee distribution breakdown */
+    getFeeStats(): Promise<ApiResponse<any>>;
+}
+
+declare class PompaflyStream {
+    private wsUrl;
+    private ws;
+    private listeners;
+    private subscriptions;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectDelay;
+    private autoReconnect;
+    private isConnected;
+    constructor(config?: PompaflyConfig);
+    /** Connect to the WebSocket server */
+    connect(): void;
+    /** Disconnect from the WebSocket server */
+    disconnect(): void;
+    /** Subscribe to real-time updates for specific token mints */
+    subscribe(mints: string[]): void;
+    /** Unsubscribe from specific token mints */
+    unsubscribe(mints: string[]): void;
+    /** Listen for price update events */
+    onPrice(handler: (event: PriceEvent) => void): () => void;
+    /** Listen for new trade events */
+    onTrade(handler: (event: TradeEvent) => void): () => void;
+    /** Listen for pool status change events */
+    onStatus(handler: (event: StatusEvent) => void): () => void;
+    /** Listen for all events */
+    onAny(handler: StreamEventHandler): () => void;
+    /** Check if connected */
+    get connected(): boolean;
+    /** Get currently subscribed mints */
+    get subscribedMints(): string[];
+    private addListener;
+    private handleMessage;
+}
+
+/**
+ * Derive all PDAs for a given mint and program ID.
+ * Call once per pool, cache the result.
+ */
+declare function derivePoolAddresses(mint: PublicKey, programId: PublicKey): Promise<{
+    pool: PublicKey;
+    poolBump: number;
+    poolTokenVault: PublicKey;
+}>;
+/**
+ * Derive the global config PDA.
+ */
+declare function deriveGlobalConfig(programId: PublicKey): [PublicKey, number];
+/**
+ * Convert SOL to lamports.
+ */
+declare function solToLamports(sol: number): number;
+/**
+ * Convert lamports to SOL.
+ */
+declare function lamportsToSol(lamports: number | string): number;
+/**
+ * Convert token amount to base units (6 decimals).
+ */
+declare function tokensToBase(tokens: number): number;
+/**
+ * Convert base units to token amount (6 decimals).
+ */
+declare function baseToTokens(base: number | string): number;
+/** Re-export program constants */
+declare const PROGRAM_CONSTANTS: {
+    readonly TOKEN_DECIMALS: 6;
+    readonly TOTAL_SUPPLY: "1000000000000000";
+    readonly GRADUATION_THRESHOLD_SOL: 150;
+    readonly FEE_BPS: 100;
+    readonly PRIORITY_WINDOW_SECONDS: 120;
+};
+
+export { type ApiResponse, type BuyResult, type Candle, type CandleInterval, type CandleParams, type ClientOptions, type CreatePoolResult, DEVNET_CONFIG, MAINNET_CONFIG, PROGRAM_CONSTANTS, type PaginatedResponse, type PlatformStats, PompaflyAPI, PompaflyClient, type PompaflyConfig, PompaflyStream, type Pool, type PoolListParams, type PoolPrice, type PriceEvent, type SellResult, type StatusEvent, type StreamEvent, type StreamEventHandler, type Trade, type TradeEvent, type TradeListParams, type TrendingPool, type TxResult, type User, type WalletAdapter, baseToTokens, deriveGlobalConfig, derivePoolAddresses, lamportsToSol, solToLamports, tokensToBase };