@velociti/sdk 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-02-03
+
+### Added
+- **Retry Logic**: Automatic retry with exponential backoff for failed requests
+  - Configurable via `enableRetry`, `maxRetries`, and `retryDelay` options
+  - Handles rate limiting (429) and server errors (5xx) automatically
+
+- **Batch Deploy**: Deploy multiple tokens in a single API call
+  - `prepareBatchDeploy()` method for batch token creation
+  - Maximum 10 tokens per batch
+
+- **Token Analytics**: Get detailed analytics for any token
+  - `getTokenAnalytics()` for volume, holders, trades, ATH/ATL
+  - `getPriceHistory()` for historical price data
+
+- **Webhooks**: Real-time event notifications
+  - `registerWebhook()` to subscribe to token events
+  - Events: token.created, token.graduated, token.trade, fees.claimed, fees.available
+  - `listWebhooks()`, `deleteWebhook()`, `testWebhook()` management methods
+
+- **CLI Tool**: Deploy from command line
+  - `npx @velociti/sdk deploy --name "MyToken" --symbol "MTK"`
+  - `npx @velociti/sdk tokens` - list your tokens
+  - `npx @velociti/sdk analytics <mintAddress>` - view token analytics
+  - `npx @velociti/sdk config --api-key YOUR_KEY` - save API key
+
+- **React Hooks**: Easy integration with React apps
+  - `useVelocitiDeploy()` - deploy tokens with wallet adapter
+  - `useVelocitiToken()` - fetch token info
+  - `useVelocitiAnalytics()` - fetch analytics
+  - `useVelocitiMyTokens()` - list user's tokens
+  - `useVelocitiFees()` - claim fees
+
+- **Examples**:
+  - `examples/trading-bot.ts` - Automated trading bot with price monitoring
+  - Discord/Telegram notifications support
+
+### Changed
+- Improved error handling with more descriptive messages
+- Better TypeScript types for all API responses
+
+## [0.1.0] - 2026-02-03
+
+### Added
+- Initial release
+- `VelocitiClient` class for API interaction
+- `prepareTokenDeploy()` - prepare token deployment transaction
+- `submitTransaction()` - submit signed transaction
+- `deployToken()` - convenience method for full deployment flow
+- `getToken()` - fetch token info by mint address
+- `getMyTokens()` - list tokens created with API key
+- `prepareClaimFees()` - prepare fee claim transaction
+- `claimFees()` - claim accumulated transfer fees
+- `getRateLimitInfo()` - check rate limit status
+- Full TypeScript support with type definitions
+- MIT License

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * VELOCITI CLI Tool
+ * Deploy and manage tokens from the command line
+ *
+ * Usage:
+ *   npx @velociti/sdk deploy --name "MyToken" --symbol "MTK"
+ *   npx @velociti/sdk tokens
+ *   npx @velociti/sdk analytics <mintAddress>
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * VELOCITI CLI Tool
+ * Deploy and manage tokens from the command line
+ *
+ * Usage:
+ *   npx @velociti/sdk deploy --name "MyToken" --symbol "MTK"
+ *   npx @velociti/sdk tokens
+ *   npx @velociti/sdk analytics <mintAddress>
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const client_1 = require("./client");
+const web3_js_1 = require("@solana/web3.js");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// ANSI colors
+const colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+};
+function log(message, color = colors.reset) {
+    console.log(`${color}${message}${colors.reset}`);
+}
+function success(message) {
+    log(`✅ ${message}`, colors.green);
+}
+function error(message) {
+    log(`❌ ${message}`, colors.red);
+}
+function info(message) {
+    log(`ℹ️  ${message}`, colors.cyan);
+}
+function banner() {
+    console.log(colors.magenta + `
+╔═══════════════════════════════════════╗
+║         VELOCITI CLI v0.1.0           ║
+║   Solana Tax Token Launchpad          ║
+╚═══════════════════════════════════════╝
+` + colors.reset);
+}
+// Parse command line arguments
+function parseArgs(args) {
+    const parsed = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            const key = arg.slice(2);
+            const next = args[i + 1];
+            if (next && !next.startsWith('--')) {
+                parsed[key] = next;
+                i++;
+            }
+            else {
+                parsed[key] = true;
+            }
+        }
+        else if (!parsed._command) {
+            parsed._command = arg;
+        }
+        else if (!parsed._arg) {
+            parsed._arg = arg;
+        }
+    }
+    return parsed;
+}
+// Load API key from env or config file
+function loadApiKey() {
+    // Check environment variable first
+    if (process.env.VELOCITI_API_KEY) {
+        return process.env.VELOCITI_API_KEY;
+    }
+    // Check config file
+    const configPath = path.join(process.env.HOME || '', '.velociti', 'config.json');
+    if (fs.existsSync(configPath)) {
+        try {
+            const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            return config.apiKey || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+// Load wallet keypair from file
+function loadWallet(walletPath) {
+    const keyPath = walletPath ||
+        process.env.VELOCITI_WALLET ||
+        path.join(process.env.HOME || '', '.config', 'solana', 'id.json');
+    if (!fs.existsSync(keyPath)) {
+        return null;
+    }
+    try {
+        const keyData = JSON.parse(fs.readFileSync(keyPath, 'utf-8'));
+        return web3_js_1.Keypair.fromSecretKey(Uint8Array.from(keyData));
+    }
+    catch {
+        return null;
+    }
+}
+// Save API key to config
+function saveApiKey(apiKey) {
+    const configDir = path.join(process.env.HOME || '', '.velociti');
+    const configPath = path.join(configDir, 'config.json');
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+    }
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+    config.apiKey = apiKey;
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+}
+// Commands
+async function deploy(args) {
+    const apiKey = loadApiKey();
+    if (!apiKey) {
+        error('No API key found. Run: velociti config --api-key YOUR_KEY');
+        process.exit(1);
+    }
+    const wallet = loadWallet(args.wallet);
+    if (!wallet) {
+        error('No wallet found. Set VELOCITI_WALLET or use --wallet path/to/keypair.json');
+        process.exit(1);
+    }
+    const name = args.name;
+    const symbol = args.symbol;
+    const description = args.description || '';
+    const taxRate = parseFloat(args.tax) || 5;
+    const network = args.network === 'mainnet' ? 'mainnet' : 'devnet';
+    if (!name || !symbol) {
+        error('Missing required arguments: --name and --symbol');
+        process.exit(1);
+    }
+    info(`Deploying token: ${name} (${symbol})`);
+    info(`Network: ${network}`);
+    info(`Tax rate: ${taxRate}%`);
+    info(`Wallet: ${wallet.publicKey.toBase58()}`);
+    const client = new client_1.VelocitiClient({ apiKey, network });
+    const prepared = await client.prepareTokenDeploy({
+        name,
+        symbol,
+        description,
+        taxRate,
+        payerAddress: wallet.publicKey.toBase58(),
+    });
+    if (!prepared.success || !prepared.data) {
+        error(`Failed to prepare: ${prepared.error}`);
+        process.exit(1);
+    }
+    info(`Estimated fee: ${prepared.data.estimatedFee} SOL`);
+    info(`Mint address: ${prepared.data.mintAddress}`);
+    // Sign transaction
+    const tx = web3_js_1.Transaction.from(Buffer.from(prepared.data.transaction, 'base64'));
+    tx.sign(wallet);
+    const signedTx = tx.serialize().toString('base64');
+    // Submit
+    info('Submitting transaction...');
+    const result = await client.submitTransaction(signedTx);
+    if (result.success) {
+        success(`Token deployed successfully!`);
+        log(`  Signature: ${result.data?.signature}`, colors.cyan);
+        log(`  View: https://velociti.fun/token/${prepared.data.mintAddress}`, colors.cyan);
+    }
+    else {
+        error(`Deployment failed: ${result.error}`);
+        process.exit(1);
+    }
+}
+async function listTokens(args) {
+    const apiKey = loadApiKey();
+    if (!apiKey) {
+        error('No API key found. Run: velociti config --api-key YOUR_KEY');
+        process.exit(1);
+    }
+    const network = args.network === 'mainnet' ? 'mainnet' : 'devnet';
+    const client = new client_1.VelocitiClient({ apiKey, network });
+    info('Fetching your tokens...');
+    const result = await client.getMyTokens();
+    if (!result.success || !result.data) {
+        error(`Failed: ${result.error}`);
+        process.exit(1);
+    }
+    if (result.data.length === 0) {
+        info('No tokens found. Deploy one with: velociti deploy --name "MyToken" --symbol "MTK"');
+        return;
+    }
+    console.log('\nYour tokens:\n');
+    for (const token of result.data) {
+        console.log(colors.bright + token.name + colors.reset + ` (${token.symbol})`);
+        console.log(`  Mint: ${token.mintAddress}`);
+        console.log(`  Price: ${token.priceInSol} SOL ($${token.priceInUsd.toFixed(4)})`);
+        console.log(`  Progress: ${token.progress}%${token.isGraduated ? ' ✅ Graduated' : ''}`);
+        console.log('');
+    }
+}
+async function analytics(args) {
+    const apiKey = loadApiKey();
+    if (!apiKey) {
+        error('No API key found. Run: velociti config --api-key YOUR_KEY');
+        process.exit(1);
+    }
+    const mintAddress = args._arg;
+    if (!mintAddress) {
+        error('Usage: velociti analytics <mintAddress>');
+        process.exit(1);
+    }
+    const network = args.network === 'mainnet' ? 'mainnet' : 'devnet';
+    const client = new client_1.VelocitiClient({ apiKey, network });
+    info(`Fetching analytics for ${mintAddress}...`);
+    const result = await client.getTokenAnalytics(mintAddress);
+    if (!result.success || !result.data) {
+        error(`Failed: ${result.error}`);
+        process.exit(1);
+    }
+    const data = result.data;
+    console.log('\n' + colors.bright + 'Token Analytics' + colors.reset);
+    console.log('═'.repeat(40));
+    console.log(`24h Volume:     ${data.volume24h} SOL`);
+    console.log(`24h Change:     ${data.priceChange24h > 0 ? '+' : ''}${data.priceChange24h.toFixed(2)}%`);
+    console.log(`Holders:        ${data.holders}`);
+    console.log(`Total Trades:   ${data.trades}`);
+    console.log(`All-Time High:  ${data.allTimeHigh} SOL`);
+    console.log(`All-Time Low:   ${data.allTimeLow} SOL`);
+    console.log('');
+}
+async function configCmd(args) {
+    if (args['api-key']) {
+        saveApiKey(args['api-key']);
+        success('API key saved to ~/.velociti/config.json');
+    }
+    else {
+        const apiKey = loadApiKey();
+        if (apiKey) {
+            info(`Current API key: ${apiKey.slice(0, 12)}...`);
+        }
+        else {
+            info('No API key configured');
+            info('Set one with: velociti config --api-key YOUR_KEY');
+        }
+    }
+}
+function help() {
+    console.log(`
+${colors.bright}Commands:${colors.reset}
+
+  ${colors.cyan}deploy${colors.reset}     Deploy a new token
+             --name "Token Name"    (required)
+             --symbol "SYM"         (required)
+             --description "..."    (optional)
+             --tax 5                (optional, default: 5%)
+             --network devnet        (optional, default: devnet)
+             --wallet path/to/key   (optional)
+
+  ${colors.cyan}tokens${colors.reset}     List your deployed tokens
+
+  ${colors.cyan}analytics${colors.reset}  Get token analytics
+             velociti analytics <mintAddress>
+
+  ${colors.cyan}config${colors.reset}     Configure CLI
+             --api-key YOUR_KEY     Save API key
+
+  ${colors.cyan}help${colors.reset}       Show this help message
+
+${colors.bright}Environment:${colors.reset}
+
+  VELOCITI_API_KEY    Your API key
+  VELOCITI_WALLET     Path to wallet keypair file
+
+${colors.bright}Examples:${colors.reset}
+
+  velociti config --api-key vel_abc123...
+  velociti deploy --name "Moon Token" --symbol "MOON" --tax 3
+  velociti tokens
+  velociti analytics 7xKXtg...
+`);
+}
+// Main
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const command = args._command;
+    if (!command || command === 'help' || args.help) {
+        banner();
+        help();
+        return;
+    }
+    banner();
+    switch (command) {
+        case 'deploy':
+            await deploy(args);
+            break;
+        case 'tokens':
+        case 'list':
+            await listTokens(args);
+            break;
+        case 'analytics':
+            await analytics(args);
+            break;
+        case 'config':
+            await configCmd(args);
+            break;
+        default:
+            error(`Unknown command: ${command}`);
+            help();
+            process.exit(1);
+    }
+}
+main().catch(err => {
+    error(err.message);
+    process.exit(1);
+});

package/dist/client.d.ts

@@ -2,15 +2,22 @@
  * VELOCITI SDK Client
  * Main client class for interacting with the VELOCITI API
  */
-import { VelocitiConfig, DeployTokenParams, TokenInfo, ClaimFeesResult, ApiResponse, RateLimitInfo, PreparedTransaction, SubmitResult } from './types';
+import { VelocitiConfig, DeployTokenParams, TokenInfo, ClaimFeesResult, ApiResponse, RateLimitInfo, PreparedTransaction, SubmitResult, BatchDeployParams, BatchDeployResult, TokenAnalytics, WebhookConfig } from './types';
 export declare class VelocitiClient {
     private apiKey;
     private baseUrl;
     private network;
     private rateLimitInfo;
+    private enableRetry;
+    private maxRetries;
+    private retryDelay;
     constructor(config: VelocitiConfig);
     /**
-     * Make an authenticated request to the VELOCITI API
+     * Sleep helper for retry logic
+     */
+    private sleep;
+    /**
+     * Make an authenticated request to the VELOCITI API with retry logic
      */
     private request;
     /**
@@ -18,24 +25,6 @@ export declare class VelocitiClient {
      *
      * Returns an unsigned transaction that you must sign with your wallet.
      * After signing, call submitTransaction() to complete the deployment.
-     *
-     * @example
-     * ```typescript
-     * // Step 1: Prepare the transaction
-     * const prepared = await client.prepareTokenDeploy({
-     *   name: 'My Token',
-     *   symbol: 'MTK',
-     *   taxRate: 5,
-     *   payerAddress: 'YourWalletAddress...'
-     * });
-     *
-     * // Step 2: Sign with your wallet (example using @solana/web3.js)
-     * const tx = Transaction.from(Buffer.from(prepared.data.transaction, 'base64'));
-     * const signedTx = await wallet.signTransaction(tx);
-     *
-     * // Step 3: Submit the signed transaction
-     * const result = await client.submitTransaction(signedTx.serialize().toString('base64'));
-     * ```
      */
     prepareTokenDeploy(params: DeployTokenParams): Promise<ApiResponse<PreparedTransaction>>;
     /**
@@ -46,23 +35,12 @@ export declare class VelocitiClient {
     submitTransaction(signedTransaction: string): Promise<ApiResponse<SubmitResult>>;
     /**
      * Convenience method: Deploy token in one call (requires wallet adapter)
-     *
-     * This combines prepareTokenDeploy and submitTransaction.
-     * You must provide a signTransaction function from your wallet.
-     *
-     * @example
-     * ```typescript
-     * const result = await client.deployToken({
-     *   name: 'My Token',
-     *   symbol: 'MTK',
-     *   taxRate: 5,
-     *   payerAddress: wallet.publicKey.toBase58()
-     * }, async (tx) => {
-     *   return await wallet.signTransaction(tx);
-     * });
-     * ```
      */
     deployToken(params: DeployTokenParams, signTransaction: (transaction: Uint8Array) => Promise<Uint8Array>): Promise<ApiResponse<SubmitResult>>;
+    /**
+     * Prepare multiple token deployments in batch
+     */
+    prepareBatchDeploy(params: BatchDeployParams): Promise<ApiResponse<BatchDeployResult>>;
     /**
      * Get token information by mint address
      */
@@ -71,13 +49,22 @@ export declare class VelocitiClient {
      * Get all tokens created with this API key
      */
     getMyTokens(): Promise<ApiResponse<TokenInfo[]>>;
+    /**
+     * Get detailed analytics for a token
+     */
+    getTokenAnalytics(mintAddress: string): Promise<ApiResponse<TokenAnalytics>>;
+    /**
+     * Get price history for a token
+     * @param mintAddress - Token mint address
+     * @param period - Time period: '1h', '24h', '7d', '30d'
+     */
+    getPriceHistory(mintAddress: string, period?: '1h' | '24h' | '7d' | '30d'): Promise<ApiResponse<TokenAnalytics['priceHistory']>>;
     /**
      * Prepare fee claim transaction
      */
     prepareClaimFees(mintAddress: string, walletAddress: string): Promise<ApiResponse<PreparedTransaction>>;
     /**
      * Claim accumulated transfer fees for a token
-     * Combines prepare + sign + submit
      */
     claimFees(mintAddress: string, walletAddress: string, signTransaction: (transaction: Uint8Array) => Promise<Uint8Array>): Promise<ApiResponse<ClaimFeesResult>>;
     /**
@@ -87,6 +74,30 @@ export declare class VelocitiClient {
         amount: string;
         valueInSol: number;
     }>>;
+    /**
+     * Register a webhook to receive events
+     */
+    registerWebhook(config: WebhookConfig): Promise<ApiResponse<{
+        id: string;
+    }>>;
+    /**
+     * List all registered webhooks
+     */
+    listWebhooks(): Promise<ApiResponse<Array<WebhookConfig & {
+        id: string;
+    }>>>;
+    /**
+     * Delete a webhook
+     */
+    deleteWebhook(webhookId: string): Promise<ApiResponse<{
+        deleted: boolean;
+    }>>;
+    /**
+     * Test a webhook endpoint
+     */
+    testWebhook(webhookId: string): Promise<ApiResponse<{
+        sent: boolean;
+    }>>;
     /**
      * Get current rate limit status
      */
@@ -95,4 +106,11 @@ export declare class VelocitiClient {
      * Get the current network
      */
     getNetwork(): 'mainnet' | 'devnet';
+    /**
+     * Check if API key is valid
+     */
+    validateApiKey(): Promise<ApiResponse<{
+        valid: boolean;
+        tier: string;
+    }>>;
 }