@pompafly/sdk 0.1.0

package/README.md

@@ -0,0 +1,187 @@
+# @pompafly/sdk
+
+TypeScript SDK for the Pompafly token launchpad on Solana.
+
+## Install
+
+```bash
+npm install @pompafly/sdk
+```
+
+## Quick Start
+
+### Frontend (Next.js + Wallet Adapter)
+
+```typescript
+import { PompaflyClient, PompaflyAPI, PompaflyStream, DEVNET_CONFIG } from "@pompafly/sdk";
+import { useAnchorWallet } from "@solana/wallet-adapter-react";
+
+// Transaction client
+const wallet = useAnchorWallet();
+const client = new PompaflyClient({ wallet, config: DEVNET_CONFIG });
+
+// REST API
+const api = new PompaflyAPI(DEVNET_CONFIG);
+
+// Real-time stream
+const stream = new PompaflyStream(DEVNET_CONFIG);
+```
+
+### Backend (Node.js + Keypair)
+
+```typescript
+import { PompaflyClient, DEVNET_CONFIG } from "@pompafly/sdk";
+import { Keypair } from "@solana/web3.js";
+
+const keypair = Keypair.fromSecretKey(/* your secret key */);
+const client = new PompaflyClient({ keypair, config: DEVNET_CONFIG });
+```
+
+## Usage
+
+### Browse Pools
+
+```typescript
+// List trending pools
+const { data: pools } = await api.getPools({ sort: "volume", status: "active" });
+
+// Search by name
+const { data: results } = await api.getPools({ search: "DOGE" });
+
+// Get pool details
+const { data: pool } = await api.getPool("mint_address_here");
+
+// Get current price
+const { data: price } = await api.getPoolPrice("mint_address_here");
+```
+
+### Buy Tokens
+
+```typescript
+// Buy 100 tokens with 1 SOL max slippage
+const result = await client.buy("mint_address", 100, 1.0);
+console.log("Signature:", result.signature);
+
+// Priority buy (during 120s window, requires auth)
+const { data: auth } = await api.getPriorityAuth("mint_address");
+const result = await client.buy("mint_address", 100, 1.0, prioritySignerKeypair);
+```
+
+### Sell Tokens
+
+```typescript
+// Sell 50 tokens, accept any return
+const result = await client.sell("mint_address", 50);
+
+// Sell with minimum return of 0.5 SOL
+const result = await client.sell("mint_address", 50, 0.5);
+```
+
+### Create a Token
+
+```typescript
+const result = await client.createPool(
+  "My Token",           // name
+  "MYTKN",              // symbol
+  "https://meta.json",  // metadata URI
+  "myxhandle",          // X handle
+  authorityKeypair      // backend co-signer
+);
+console.log("Mint:", result.mint);
+console.log("Pool:", result.pool);
+```
+
+### Real-Time Price Feed
+
+```typescript
+const stream = new PompaflyStream();
+stream.connect();
+
+// Subscribe to specific tokens
+stream.subscribe(["mint1", "mint2"]);
+
+// Listen for price updates
+const unsub = stream.onPrice((event) => {
+  console.log(`${event.mint}: ${event.data.currentPrice}`);
+});
+
+// Listen for trades
+stream.onTrade((event) => {
+  console.log(`${event.data.type}: ${event.data.tokenAmount} tokens`);
+});
+
+// Cleanup
+unsub(); // remove listener
+stream.unsubscribe(["mint1"]);
+stream.disconnect();
+```
+
+### Authentication Flow
+
+```typescript
+// 1. Get nonce
+const { data: { nonce, message } } = await api.getNonce(wallet.publicKey.toBase58());
+
+// 2. Sign with wallet (frontend)
+const signature = await wallet.signMessage(new TextEncoder().encode(message));
+
+// 3. Verify and get JWT
+const { data: { token, user } } = await api.verifyWallet(
+  wallet.publicKey.toBase58(),
+  bs58.encode(signature)
+);
+// JWT is automatically stored in the API client
+
+// 4. Link X account (redirects to Twitter OAuth)
+window.location.href = api.getXLoginUrl();
+```
+
+### Charts
+
+```typescript
+// Get 1-hour candles for the last 24 hours
+const { data: candles } = await api.getCandles("mint_address", {
+  interval: "1h",
+  from: Math.floor(Date.now() / 1000) - 86400,
+  limit: 24,
+});
+```
+
+### Platform Stats
+
+```typescript
+const { data: stats } = await api.getStats();
+console.log("Total pools:", stats.totalPoolsCreated);
+console.log("Graduation rate:", stats.graduationRate);
+
+const { data: trending } = await api.getTrending(10);
+```
+
+## Utilities
+
+```typescript
+import { solToLamports, lamportsToSol, tokensToBase, baseToTokens } from "@pompafly/sdk";
+
+solToLamports(1.5);      // 1500000000
+lamportsToSol(1500000000); // 1.5
+tokensToBase(100);        // 100000000
+baseToTokens(100000000);  // 100
+```
+
+## Configuration
+
+```typescript
+import { DEVNET_CONFIG, MAINNET_CONFIG } from "@pompafly/sdk";
+
+// Or custom config
+const config = {
+  rpcUrl: "https://my-rpc.com",
+  programId: "FnBDGeXKx3CsrFqxfKrLMsuNeUmMZPP19DbLbmqj8wCZ",
+  apiUrl: "https://api.pompafly.fun",
+  wsUrl: "wss://api.pompafly.fun/ws",
+};
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -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 };