@oobe-protocol-labs/synapse-client-sdk 1.0.0-beta

package/dist/esm/nft/clients/magic-eden-client.js

@@ -0,0 +1,259 @@
+/**
+ * Magic Eden API Client
+ * Integration with Magic Eden marketplace API
+ * @see https://api.magiceden.dev/
+ * @see https://docs.magiceden.io/
+ */
+/**
+ * MagicEdenClient - Production-ready Magic Eden API integration
+ * Handles rate limiting, error handling, and response validation
+ */
+export class MagicEdenClient {
+    baseUrl;
+    apiKey;
+    timeout;
+    fetchImpl;
+    logLevel;
+    rateLimiter;
+    constructor(config) {
+        this.baseUrl = config?.baseUrl || 'https://api-mainnet.magiceden.dev/v2';
+        this.apiKey = config?.apiKey;
+        this.timeout = config?.timeout || 10000;
+        this.logLevel = config?.logLevel || 'error';
+        // Rate limiter: default 10 req/s = 100ms between requests
+        const rateLimit = config?.rateLimit || 10;
+        this.rateLimiter = {
+            lastRequest: 0,
+            minInterval: 1000 / rateLimit,
+        };
+        // Cross-platform fetch support
+        if (config?.fetch) {
+            this.fetchImpl = config.fetch;
+        }
+        else if (typeof globalThis.fetch !== 'undefined') {
+            this.fetchImpl = globalThis.fetch.bind(globalThis);
+        }
+        else {
+            // Node <18 requires fetch polyfill
+            throw new Error('fetch is not available. Please provide a fetch implementation via config.fetch or upgrade to Node 18+');
+        }
+    }
+    /**
+     * Get collection statistics from Magic Eden
+     * @param symbol - Collection symbol (e.g. "okay_bears")
+     * @returns Collection statistics including floor price, volume
+     */
+    async getCollectionStats(symbol) {
+        this.logDebug(`Fetching collection stats for: ${symbol}`);
+        const url = `${this.baseUrl}/collections/${symbol}/stats`;
+        const response = await this.makeRequest(url);
+        this.logInfo(`Collection stats fetched: ${symbol} - Floor: ${response.floorPrice} SOL`);
+        return response;
+    }
+    /**
+     * Get collection information
+     * @param symbol - Collection symbol
+     * @returns Collection metadata and info
+     */
+    async getCollectionInfo(symbol) {
+        this.logDebug(`Fetching collection info for: ${symbol}`);
+        const url = `${this.baseUrl}/collections/${symbol}`;
+        const response = await this.makeRequest(url);
+        this.logInfo(`Collection info fetched: ${symbol} - ${response.name}`);
+        return response;
+    }
+    /**
+     * Get current floor price for a collection
+     * @param symbol - Collection symbol
+     * @returns Floor price in SOL (not lamports)
+     */
+    async getFloorPrice(symbol) {
+        const stats = await this.getCollectionStats(symbol);
+        return stats.floorPrice;
+    }
+    /**
+     * Get active listings for a collection
+     * @param symbol - Collection symbol
+     * @param options - Pagination options
+     * @returns Array of active listings
+     */
+    async getListings(symbol, options) {
+        this.logDebug(`Fetching listings for: ${symbol}`);
+        const params = new URLSearchParams();
+        if (options?.offset)
+            params.append('offset', options.offset.toString());
+        if (options?.limit)
+            params.append('limit', options.limit.toString());
+        const url = `${this.baseUrl}/collections/${symbol}/listings?${params.toString()}`;
+        const response = await this.makeRequest(url);
+        this.logInfo(`Fetched ${response.length} listings for: ${symbol}`);
+        return response;
+    }
+    /**
+     * Get collection activities (sales, listings, etc.)
+     * @param symbol - Collection symbol
+     * @param options - Pagination options
+     * @returns Array of activities
+     */
+    async getCollectionActivities(symbol, options) {
+        this.logDebug(`Fetching activities for: ${symbol}`);
+        const params = new URLSearchParams();
+        if (options?.offset)
+            params.append('offset', options.offset.toString());
+        if (options?.limit)
+            params.append('limit', options.limit.toString());
+        const url = `${this.baseUrl}/collections/${symbol}/activities?${params.toString()}`;
+        const response = await this.makeRequest(url);
+        this.logInfo(`Fetched ${response.length} activities for: ${symbol}`);
+        return response;
+    }
+    /**
+     * Get listing for a specific NFT token
+     * @param mintAddress - NFT mint address
+     * @returns Listing information or null if not listed
+     */
+    async getTokenListing(mintAddress) {
+        this.logDebug(`Fetching listing for token: ${mintAddress}`);
+        const url = `${this.baseUrl}/tokens/${mintAddress}/listings`;
+        try {
+            const response = await this.makeRequest(url);
+            if (response.length === 0) {
+                this.logDebug(`No listing found for token: ${mintAddress}`);
+                return null;
+            }
+            // Return the first (active) listing
+            this.logInfo(`Listing found for token: ${mintAddress}`);
+            return response[0];
+        }
+        catch (error) {
+            if (this.isNotFoundError(error)) {
+                this.logDebug(`No listing found for token: ${mintAddress}`);
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get recent sales for a collection
+     * @param symbol - Collection symbol
+     * @param options - Pagination options
+     * @returns Array of recent sales (filtered buyNow activities)
+     */
+    async getSales(symbol, options) {
+        const activities = await this.getCollectionActivities(symbol, options);
+        // Filter for sales only (buyNow type)
+        return activities.filter((activity) => activity.type === 'buyNow');
+    }
+    /**
+     * Search for collections by name
+     * @param query - Search query
+     * @param limit - Maximum results
+     * @returns Array of matching collections
+     */
+    async searchCollections(query, limit = 20) {
+        this.logDebug(`Searching collections: ${query}`);
+        const params = new URLSearchParams({
+            q: query,
+            limit: limit.toString(),
+        });
+        const url = `${this.baseUrl}/collections?${params.toString()}`;
+        const response = await this.makeRequest(url);
+        this.logInfo(`Found ${response.length} collections for: ${query}`);
+        return response;
+    }
+    /**
+     * Health check - verify Magic Eden API is accessible
+     * @returns True if API is healthy
+     */
+    async healthCheck() {
+        try {
+            // Try fetching a popular collection as health check
+            await this.getCollectionStats('okay_bears');
+            return true;
+        }
+        catch (error) {
+            this.logError(`Magic Eden API health check failed: ${error.message}`);
+            return false;
+        }
+    }
+    // =========================================================================
+    // Private Methods
+    // =========================================================================
+    async makeRequest(url) {
+        // Rate limiting
+        await this.enforceRateLimit();
+        // Build headers
+        const headers = {
+            'Accept': 'application/json',
+        };
+        if (this.apiKey) {
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        }
+        // Create abort controller for timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            this.logDebug(`Request: GET ${url}`);
+            const response = await this.fetchImpl(url, {
+                method: 'GET',
+                headers,
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            // Handle non-OK responses
+            if (!response.ok) {
+                const errorBody = await response.text();
+                let errorMessage = `Magic Eden API error: ${response.status} ${response.statusText}`;
+                try {
+                    const errorJson = JSON.parse(errorBody);
+                    errorMessage = `Magic Eden API error: ${errorJson.error}`;
+                }
+                catch {
+                    errorMessage += ` - ${errorBody.substring(0, 200)}`;
+                }
+                throw new Error(errorMessage);
+            }
+            // Parse JSON response
+            const data = await response.json();
+            this.logDebug(`Response: ${response.status} - ${JSON.stringify(data).substring(0, 100)}...`);
+            return data;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error.name === 'AbortError') {
+                throw new Error(`Magic Eden API request timeout after ${this.timeout}ms`);
+            }
+            throw error;
+        }
+    }
+    async enforceRateLimit() {
+        const now = Date.now();
+        const timeSinceLastRequest = now - this.rateLimiter.lastRequest;
+        if (timeSinceLastRequest < this.rateLimiter.minInterval) {
+            const waitTime = this.rateLimiter.minInterval - timeSinceLastRequest;
+            this.logDebug(`Rate limit: waiting ${waitTime}ms`);
+            await new Promise((resolve) => setTimeout(resolve, waitTime));
+        }
+        this.rateLimiter.lastRequest = Date.now();
+    }
+    isNotFoundError(error) {
+        return (error instanceof Error &&
+            (error.message.includes('404') || error.message.includes('not found')));
+    }
+    logDebug(message) {
+        if (this.logLevel === 'debug') {
+            console.log(`[MagicEdenClient:DEBUG] ${message}`);
+        }
+    }
+    logInfo(message) {
+        if (this.logLevel === 'debug' || this.logLevel === 'info') {
+            console.log(`[MagicEdenClient:INFO] ${message}`);
+        }
+    }
+    logError(message) {
+        if (this.logLevel !== 'none') {
+            console.error(`[MagicEdenClient:ERROR] ${message}`);
+        }
+    }
+}
+//# sourceMappingURL=magic-eden-client.js.map

package/dist/esm/nft/clients/magic-eden-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"magic-eden-client.js","sourceRoot":"","sources":["../../../../src/nft/clients/magic-eden-client.ts"],"names":[],"mappings":"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"}

package/dist/esm/nft/clients/metaplex-onchain-client.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Metaplex On-Chain Client
+ * Direct on-chain NFT collection analysis using Solana RPC and DAS API
+ * Alternative to marketplace APIs for decentralized, trustless data
+ * @see https://developers.metaplex.com/
+ */
+import { Connection } from '@solana/web3.js';
+export interface MetaplexOnChainConfig {
+    connection: Connection;
+    /** Optional RPC endpoint override */
+    rpcEndpoint?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Enable detailed logging */
+    logLevel?: 'debug' | 'info' | 'error' | 'none';
+    /** DAS (Digital Asset Standard) API endpoint for faster queries (Helius, Triton, etc.) */
+    dasEndpoint?: string;
+}
+export interface OnChainCollectionMetadata {
+    collectionMint: string;
+    name: string;
+    symbol: string;
+    uri: string;
+    updateAuthority: string;
+    creators: Array<{
+        address: string;
+        verified: boolean;
+        share: number;
+    }>;
+    sellerFeeBasisPoints: number;
+    isMutable: boolean;
+    collection?: {
+        verified: boolean;
+        key: string;
+    };
+}
+export interface OnChainCollectionStats {
+    collectionMint: string;
+    totalSupply: number;
+    verifiedNFTs: number;
+    holders: number;
+    uniqueHolders: number;
+    holderDistribution: {
+        whales: number;
+        medium: number;
+        retail: number;
+    };
+    topHolders: Array<{
+        address: string;
+        count: number;
+        percentage: number;
+    }>;
+    nftsByCreator: number;
+    dataSource: 'on-chain';
+    timestamp: number;
+}
+export interface OnChainNFT {
+    mint: string;
+    owner: string;
+    metadata: {
+        name: string;
+        symbol: string;
+        uri: string;
+        sellerFeeBasisPoints: number;
+    };
+    collection?: string;
+    verified: boolean;
+}
+/**
+ * MetaplexOnChainClient - Direct on-chain NFT analysis
+ *
+ * Provides trustless, decentralized collection statistics without
+ * relying on centralized marketplace APIs. Uses Metaplex standards,
+ * Solana RPC queries, and optional DAS API for faster bulk operations.
+ *
+ * **Use Cases:**
+ * - Collections not listed on major marketplaces
+ * - Trustless verification of collection data
+ * - Real-time holder distribution analysis
+ * - Independent supply and holder calculations
+ *
+ * **Trade-offs:**
+ * - Slower than marketplace APIs (requires multiple RPC calls)
+ * - No historical price data (no marketplace context)
+ * - No marketplace-specific metrics (listings, sales, volume)
+ * - Higher RPC costs for large collections (1000+ NFTs)
+ *
+ * **Recommended:** Use with Helius DAS API for production deployments
+ */
+export declare class MetaplexOnChainClient {
+    private readonly connection;
+    private readonly rpcEndpoint;
+    private readonly timeout;
+    private readonly logLevel;
+    private readonly dasEndpoint?;
+    private readonly umi;
+    constructor(config: MetaplexOnChainConfig);
+    /**
+     * Get collection metadata from on-chain data using Metaplex standards
+     * @param collectionMint - Collection mint address
+     * @returns Collection metadata parsed from Metaplex Token Metadata
+     */
+    getCollectionMetadata(collectionMint: string): Promise<OnChainCollectionMetadata>;
+    /**
+     * Get all NFTs in a collection by creator
+     * Uses DAS API if available (recommended), falls back to RPC
+     * @param creatorAddress - Creator/collection address
+     * @param options - Query options
+     * @returns Array of NFTs with owner and metadata
+     */
+    getCollectionNFTs(creatorAddress: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<OnChainNFT[]>;
+    /**
+     * Get NFTs via DAS (Digital Asset Standard) API - RECOMMENDED
+     * Supports Helius, Triton, and other DAS-compatible providers
+     * @private
+     */
+    private getCollectionNFTsViaDAS;
+    /**
+     * Calculate on-chain collection statistics
+     * Analyzes holder distribution, supply, and concentration risk
+     * @param creatorAddress - Creator/collection address
+     * @returns Comprehensive on-chain statistics
+     */
+    calculateOnChainStats(creatorAddress: string): Promise<OnChainCollectionStats>;
+    /**
+     * Get holder distribution analysis with concentration risk
+     * Uses Herfindahl-Hirschman Index (HHI) for concentration measurement
+     * @param creatorAddress - Creator/collection address
+     * @returns Holder distribution data with risk score
+     */
+    getHolderDistribution(creatorAddress: string): Promise<{
+        totalHolders: number;
+        distribution: Map<string, number>;
+        concentrationRisk: number;
+    }>;
+    /**
+     * Get all NFTs owned by a specific wallet
+     * @param ownerAddress - Wallet address
+     * @returns Array of owned NFTs
+     */
+    getNFTsByOwner(ownerAddress: string): Promise<OnChainNFT[]>;
+    /**
+     * Health check - verify RPC and DAS API connectivity
+     * @returns True if services are accessible
+     */
+    healthCheck(): Promise<boolean>;
+    private logDebug;
+    private logInfo;
+    private logError;
+}
+//# sourceMappingURL=metaplex-onchain-client.d.ts.map

package/dist/esm/nft/clients/metaplex-onchain-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metaplex-onchain-client.d.ts","sourceRoot":"","sources":["../../../../src/nft/clients/metaplex-onchain-client.ts"],"names":[],"mappings":"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"}